<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>PyInstaller Manual</title>
<meta name="authors" content="David Cortesi  based on structure by Giovanni Bajo &amp; William Caban  based on Gordon McMillan's manual" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="stylesheets/default.css" type="text/css" />
</head>
<body>
<div class="document" id="pyinstaller-manual">
<h1 class="title">PyInstaller Manual</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Version:</th>
<td>PyInstaller 3.1</td></tr>
<tr class="field"><th class="docinfo-name">Homepage:</th><td class="field-body"><a class="reference external" href="http://www.pyinstaller.org">http://www.pyinstaller.org</a></td>
</tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:pyinstaller&#64;googlegroups.com">pyinstaller&#64;googlegroups.com</a></td></tr>
<tr><th class="docinfo-name">Authors:</th>
<td>David Cortesi
<br />based on structure by Giovanni Bajo &amp; William Caban
<br />based on Gordon McMillan's manual</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#in-brief" id="id2">In Brief</a><ul>
<li><a class="reference internal" href="#what-s-new-this-release" id="id3">What's New This Release</a></li>
</ul>
</li>
<li><a class="reference internal" href="#requirements" id="id4">Requirements</a><ul>
<li><a class="reference internal" href="#windows" id="id5">Windows</a></li>
<li><a class="reference internal" href="#mac-os-x" id="id6">Mac&nbsp;OS&nbsp;X</a></li>
<li><a class="reference internal" href="#linux" id="id7">Linux</a></li>
<li><a class="reference internal" href="#aix-solaris-and-freebsd" id="id8">AIX, Solaris, and FreeBSD</a></li>
</ul>
</li>
<li><a class="reference internal" href="#license" id="id9">License</a></li>
<li><a class="reference internal" href="#how-to-contribute" id="id10">How To Contribute</a></li>
<li><a class="reference internal" href="#how-to-install-pyinstaller" id="id11">How to Install <cite>PyInstaller</cite></a><ul>
<li><a class="reference internal" href="#installing-in-windows" id="id12">Installing in Windows</a></li>
<li><a class="reference internal" href="#installing-in-mac-os-x" id="id13">Installing in Mac&nbsp;OS&nbsp;X</a></li>
<li><a class="reference internal" href="#installing-from-the-archive" id="id14">Installing from the archive</a></li>
<li><a class="reference internal" href="#verifying-the-installation" id="id15">Verifying the installation</a></li>
<li><a class="reference internal" href="#installed-commands" id="id16">Installed commands</a></li>
</ul>
</li>
<li><a class="reference internal" href="#what-pyinstaller-does-and-how-it-does-it" id="id17">What <cite>PyInstaller</cite> Does and How It Does It</a><ul>
<li><a class="reference internal" href="#analysis-finding-the-files-your-program-needs" id="id18">Analysis: Finding the Files Your Program Needs</a></li>
<li><a class="reference internal" href="#bundling-to-one-folder" id="id19">Bundling to One Folder</a></li>
<li><a class="reference internal" href="#how-the-one-folder-program-works" id="id20">How the One-Folder Program Works</a></li>
<li><a class="reference internal" href="#bundling-to-one-file" id="id21">Bundling to One File</a></li>
<li><a class="reference internal" href="#how-the-one-file-program-works" id="id22">How the One-File Program Works</a></li>
<li><a class="reference internal" href="#using-a-console-window" id="id23">Using a Console Window</a></li>
<li><a class="reference internal" href="#hiding-the-source-code" id="id24">Hiding the Source Code</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-pyinstaller" id="id25">Using PyInstaller</a><ul>
<li><a class="reference internal" href="#options" id="id26">Options</a><ul>
<li><a class="reference internal" href="#general-options" id="id27">General Options</a></li>
<li><a class="reference internal" href="#what-to-generate" id="id28">What to generate</a></li>
<li><a class="reference internal" href="#what-to-bundle-where-to-search" id="id29">What to bundle, where to search</a></li>
<li><a class="reference internal" href="#how-to-generate" id="id30">How to generate</a></li>
<li><a class="reference internal" href="#windows-and-mac-os-x-specific-options" id="id31">Windows and Mac OS X specific options</a></li>
<li><a class="reference internal" href="#windows-specific-options" id="id32">Windows specific options</a></li>
<li><a class="reference internal" href="#windows-side-by-side-assembly-searching-options-advanced" id="id33">Windows Side-by-side Assembly searching options (advanced)</a></li>
<li><a class="reference internal" href="#mac-os-x-specific-options" id="id34">Mac OS X specific options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#shortening-the-command" id="id35">Shortening the Command</a></li>
<li><a class="reference internal" href="#using-upx" id="id36">Using UPX</a></li>
<li><a class="reference internal" href="#encrypting-python-bytecode" id="id37">Encrypting Python Bytecode</a></li>
<li><a class="reference internal" href="#supporting-multiple-platforms" id="id38">Supporting Multiple Platforms</a><ul>
<li><a class="reference internal" href="#supporting-multiple-python-environments" id="id39">Supporting Multiple Python Environments</a></li>
<li><a class="reference internal" href="#supporting-multiple-operating-systems" id="id40">Supporting Multiple Operating Systems</a></li>
</ul>
</li>
<li><a class="reference internal" href="#making-linux-apps-forward-compatible" id="id41">Making Linux Apps Forward-Compatible</a></li>
<li><a class="reference internal" href="#capturing-windows-version-data" id="id42">Capturing Windows Version Data</a></li>
<li><a class="reference internal" href="#building-mac-os-x-app-bundles" id="id43">Building Mac&nbsp;OS&nbsp;X App Bundles</a><ul>
<li><a class="reference internal" href="#making-mac-os-x-apps-forward-compatible" id="id44">Making Mac&nbsp;OS&nbsp;X apps Forward-Compatible</a></li>
<li><a class="reference internal" href="#building-32-bit-apps-in-mac-os-x" id="id45">Building 32-bit Apps in Mac&nbsp;OS&nbsp;X</a></li>
<li><a class="reference internal" href="#getting-the-opened-document-names" id="id46">Getting the Opened Document Names</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#run-time-information" id="id47">Run-time Information</a><ul>
<li><a class="reference internal" href="#using-file-and-sys-meipass" id="id48">Using <tt class="docutils literal">__file__</tt> and <tt class="docutils literal">sys._MEIPASS</tt></a></li>
<li><a class="reference internal" href="#using-sys-executable-and-sys-argv-0" id="id49">Using <tt class="docutils literal">sys.executable</tt> and <tt class="docutils literal">sys.argv[0]</tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-spec-files" id="id50">Using Spec Files</a><ul>
<li><a class="reference internal" href="#spec-file-operation" id="id51">Spec File Operation</a></li>
<li><a class="reference internal" href="#adding-files-to-the-bundle" id="id52">Adding Files to the Bundle</a><ul>
<li><a class="reference internal" href="#adding-data-files" id="id53">Adding Data Files</a></li>
<li><a class="reference internal" href="#using-data-files-from-a-module" id="id54">Using Data Files from a Module</a></li>
<li><a class="reference internal" href="#adding-binary-files" id="id55">Adding Binary Files</a></li>
<li><a class="reference internal" href="#advanced-methods-of-adding-files" id="id56">Advanced Methods of Adding Files</a></li>
</ul>
</li>
<li><a class="reference internal" href="#giving-run-time-python-options" id="id57">Giving Run-time Python Options</a></li>
<li><a class="reference internal" href="#spec-file-options-for-a-mac-os-x-bundle" id="id58">Spec File Options for a Mac&nbsp;OS&nbsp;X Bundle</a></li>
<li><a class="reference internal" href="#multipackage-bundles" id="id59">Multipackage Bundles</a><ul>
<li><a class="reference internal" href="#example-merge-spec-file" id="id60">Example MERGE spec file</a></li>
</ul>
</li>
<li><a class="reference internal" href="#globals-available-to-the-spec-file" id="id61">Globals Available to the Spec File</a></li>
</ul>
</li>
<li><a class="reference internal" href="#when-things-go-wrong" id="id62">When Things Go Wrong</a><ul>
<li><a class="reference internal" href="#recipes-and-examples-for-specific-problems" id="id63">Recipes and Examples for Specific Problems</a></li>
<li><a class="reference internal" href="#finding-out-what-went-wrong" id="id64">Finding out What Went Wrong</a><ul>
<li><a class="reference internal" href="#build-time-messages" id="id65">Build-time Messages</a></li>
<li><a class="reference internal" href="#build-time-dependency-graph" id="id66">Build-Time Dependency Graph</a></li>
<li><a class="reference internal" href="#build-time-python-errors" id="id67">Build-Time Python Errors</a></li>
<li><a class="reference internal" href="#getting-debug-messages" id="id68">Getting Debug Messages</a></li>
<li><a class="reference internal" href="#getting-python-s-verbose-imports" id="id69">Getting Python's Verbose Imports</a></li>
</ul>
</li>
<li><a class="reference internal" href="#helping-pyinstaller-find-modules" id="id70">Helping PyInstaller Find Modules</a><ul>
<li><a class="reference internal" href="#extending-the-path" id="id71">Extending the Path</a></li>
<li><a class="reference internal" href="#listing-hidden-imports" id="id72">Listing Hidden Imports</a></li>
<li><a class="reference internal" href="#extending-a-package-s-path" id="id73">Extending a Package's <tt class="docutils literal">__path__</tt></a></li>
<li><a class="reference internal" href="#changing-runtime-behavior" id="id74">Changing Runtime Behavior</a></li>
</ul>
</li>
<li><a class="reference internal" href="#getting-the-latest-version" id="id75">Getting the Latest Version</a></li>
<li><a class="reference internal" href="#asking-for-help" id="id76">Asking for Help</a></li>
</ul>
</li>
<li><a class="reference internal" href="#advanced-topics" id="id77">Advanced Topics</a><ul>
<li><a class="reference internal" href="#the-bootstrap-process-in-detail" id="id78">The Bootstrap Process in Detail</a><ul>
<li><a class="reference internal" href="#bootloader" id="id79">Bootloader</a></li>
<li><a class="reference internal" href="#python-imports-in-a-bundled-app" id="id80">Python imports in a bundled app</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-toc-and-tree-classes" id="id81">The TOC and Tree Classes</a><ul>
<li><a class="reference internal" href="#toc-class-table-of-contents" id="id82">TOC Class (Table of Contents)</a></li>
<li><a class="reference internal" href="#the-tree-class" id="id83">The Tree Class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#inspecting-archives" id="id84">Inspecting Archives</a><ul>
<li><a class="reference internal" href="#zlibarchive" id="id85">ZlibArchive</a></li>
<li><a class="reference internal" href="#carchive" id="id86">CArchive</a></li>
<li><a class="reference internal" href="#using-pyi-archive-viewer" id="id87">Using pyi-archive_viewer</a></li>
</ul>
</li>
<li><a class="reference internal" href="#inspecting-executables" id="id88">Inspecting Executables</a></li>
<li><a class="reference internal" href="#creating-a-reproducible-build" id="id89">Creating a Reproducible Build</a></li>
</ul>
</li>
<li><a class="reference internal" href="#understanding-pyinstaller-hooks" id="id90">Understanding PyInstaller Hooks</a><ul>
<li><a class="reference internal" href="#how-a-hook-is-loaded" id="id91">How a Hook Is Loaded</a><ul>
<li><a class="reference internal" href="#hook-global-variables" id="id92">Hook Global Variables</a></li>
<li><a class="reference internal" href="#useful-items-in-pyinstaller-compat" id="id93">Useful Items in <tt class="docutils literal">PyInstaller.compat</tt></a></li>
<li><a class="reference internal" href="#useful-items-in-pyinstaller-utils-hooks" id="id94">Useful Items in <tt class="docutils literal">PyInstaller.utils.hooks</tt></a></li>
<li><a class="reference internal" href="#the-hook-hook-api-function" id="id95">The <tt class="docutils literal">hook(hook_api)</tt> Function</a></li>
<li><a class="reference internal" href="#the-pre-find-module-path-pfmp-api-method" id="id96">The <tt class="docutils literal">pre_find_module_path( pfmp_api )</tt> Method</a></li>
<li><a class="reference internal" href="#the-pre-safe-import-module-psim-api-method" id="id97">The <tt class="docutils literal">pre_safe_import_module( psim_api )</tt> Method</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#building-the-bootloader" id="id98">Building the Bootloader</a><ul>
<li><a class="reference internal" href="#development-tools" id="id99">Development tools</a></li>
<li><a class="reference internal" href="#building-for-windows" id="id100">Building for Windows</a></li>
<li><a class="reference internal" href="#building-for-linux" id="id101">Building for LINUX</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="in-brief">
<h1><a class="toc-backref" href="#id2">In Brief</a></h1>
<p><cite>PyInstaller</cite> bundles a Python application and all its dependencies into
a single package.
The user can run the packaged app without installing a Python interpreter or any modules.
<cite>PyInstaller</cite> supports Python 2.7 and Python 3.3+,
and correctly bundles the major Python packages
such as numpy, PyQt, Django, wxPython, and others.</p>
<p><cite>PyInstaller</cite> is tested against Windows, Mac&nbsp;OS&nbsp;X, and Linux.
However, it is not a cross-compiler:
to make a Windows app you run <cite>PyInstaller</cite> in Windows;
to make a Linux app you run it in Linux, etc.
<cite>PyInstaller</cite> has been used successfully with AIX, Solaris, and FreeBSD,
but is not tested against them.</p>
<div class="section" id="what-s-new-this-release">
<h2><a class="toc-backref" href="#id3">What's New This Release</a></h2>
<p>Release 3.0 is a major rewrite that adds Python 3 support,
better code quality through use of automated testing,
and resolutions for many old issues.</p>
<p>Functional changes include
removal of support for Python prior to 2.7,
an easier way to include data files
in the bundle (<a class="reference internal" href="#adding-files-to-the-bundle">Adding Files to the Bundle</a>),
and changes to the &quot;hook&quot; API (<a class="reference internal" href="#understanding-pyinstaller-hooks">Understanding PyInstaller Hooks</a>).</p>
</div>
</div>
<div class="section" id="requirements">
<h1><a class="toc-backref" href="#id4">Requirements</a></h1>
<div class="section" id="windows">
<h2><a class="toc-backref" href="#id5">Windows</a></h2>
<p><cite>PyInstaller</cite> runs in Windows XP or newer.
It can create graphical windowed apps (apps that do not need a command window).</p>
<p><cite>PyInstaller</cite> requires the <a class="reference external" href="http://sourceforge.net/projects/pywin32/files/">PyWin32</a> or <a class="reference external" href="https://pypi.python.org/pypi/pypiwin32/219">pypiwin32</a> Python extension for Windows.
If you install <cite>PyInstaller</cite> using pip, and PyWin32 is not found,
pypiwin32 is automatically installed.</p>
<p>The <a class="reference external" href="https://sites.google.com/site/pydatalog/python/pip-for-windows">pip-Win</a> package is also recommended but not required.</p>
</div>
<div class="section" id="mac-os-x">
<h2><a class="toc-backref" href="#id6">Mac&nbsp;OS&nbsp;X</a></h2>
<p><cite>PyInstaller</cite> runs in Mac OS X 10.6 (Snow Leopard) or newer.
It can build graphical windowed apps (apps that do not use a terminal window).
PyInstaller builds apps that are compatible with the Mac OS X release in
which you run it, and following releases.
It can build 32-bit binaries in Mac OS X releases that support them.</p>
</div>
<div class="section" id="linux">
<h2><a class="toc-backref" href="#id7">Linux</a></h2>
<p><cite>PyInstaller</cite> requires the <tt class="docutils literal">ldd</tt> terminal application to discover
the shared libraries required by each program or shared library.
It is typically found in the distribution-package <tt class="docutils literal">glibc</tt> or <tt class="docutils literal"><span class="pre">libc-bin</span></tt>.</p>
<p>It also requires the <tt class="docutils literal">objdump</tt> terminal application to extract
information from object files.
This is typically found in the distribution-package <tt class="docutils literal">binutils</tt>.</p>
</div>
<div class="section" id="aix-solaris-and-freebsd">
<h2><a class="toc-backref" href="#id8">AIX, Solaris, and FreeBSD</a></h2>
<p>Users have reported success running <cite>PyInstaller</cite> on these platforms,
but it is not tested on them.
The <tt class="docutils literal">ldd</tt> and <tt class="docutils literal">objdump</tt> commands are needed.</p>
<p>Before using <cite>PyInstaller</cite> in these systems
you must compile a bootloader; see <a class="reference internal" href="#building-the-bootloader">Building the Bootloader</a>.</p>
</div>
</div>
<div class="section" id="license">
<h1><a class="toc-backref" href="#id9">License</a></h1>
<p><cite>PyInstaller</cite> is distributed under the <a class="reference external" href="https://raw.github.com/pyinstaller/pyinstaller/develop/COPYING.txt">GPL License</a> but with
an exception that allows you to use it to build commercial products:</p>
<blockquote>
<ol class="arabic simple">
<li>You may use PyInstaller to bundle commercial applications out of your
source code.</li>
<li>The executable bundles generated by PyInstaller from your source code
can be shipped with whatever license you want.</li>
<li>You may modify PyInstaller for your own needs but changes to the
PyInstaller source code fall under the terms of the GPL license.
That is, if you distribute your modifications you must distribute
them under GPL terms.</li>
</ol>
</blockquote>
<p>For updated information or clarification see our
<a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/FAQ">FAQ</a> at the <a class="reference external" href="http://www.pyinstaller.org">PyInstaller</a> home page.</p>
</div>
<div class="section" id="how-to-contribute">
<h1><a class="toc-backref" href="#id10">How To Contribute</a></h1>
<p><cite>PyInstaller</cite> is an open-source project that is created and
maintained by volunteers.
At <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/Community">Pyinstaller.org</a> you find links to the mailing list,
IRC channel, and Git repository,
and the important <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/How-to-Contribute">How to Contribute</a> link.
Contributions to code and documentation are welcome,
as well as tested hooks for installing other packages.</p>
</div>
<div class="section" id="how-to-install-pyinstaller">
<h1><a class="toc-backref" href="#id11">How to Install <cite>PyInstaller</cite></a></h1>
<p><cite>PyInstaller</cite> is a normal Python package.
You can download the archive from <a class="reference external" href="https://pypi.python.org/pypi/PyInstaller/">PyPi</a>,
but it is easier to install using <a class="reference external" href="http://www.pip-installer.org/">pip</a> where is is available,
for example:</p>
<pre class="literal-block">
pip install pyinstaller
</pre>
<p>or upgrade to a newer version:</p>
<pre class="literal-block">
pip install --upgrade pyinstaller
</pre>
<div class="section" id="installing-in-windows">
<h2><a class="toc-backref" href="#id12">Installing in Windows</a></h2>
<p>For Windows, <a class="reference external" href="http://sourceforge.net/projects/pywin32/files/">PyWin32</a> or the more recent <a class="reference external" href="https://pypi.python.org/pypi/pypiwin32/219">pypiwin32</a>, is a prerequisite.
The latter is installed automatically when you install <cite>PyInstaller</cite>
using <a class="reference external" href="http://www.pip-installer.org/">pip</a> or <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy_install</a>.
If necessary, follow the <a class="reference external" href="https://pypi.python.org/pypi/pypiwin32/219">pypiwin32</a> link to install it manually.</p>
<p>It is particularly easy to use <a class="reference external" href="https://sites.google.com/site/pydatalog/python/pip-for-windows">pip-Win</a> to install <cite>PyInstaller</cite>
along with the correct version of <a class="reference external" href="http://sourceforge.net/projects/pywin32/files/">PyWin32</a>.
<a class="reference external" href="https://sites.google.com/site/pydatalog/python/pip-for-windows">pip-Win</a> also provides <a class="reference external" href="http://www.virtualenv.org/">virtualenv</a>, which makes it simple
to maintain multiple different Python interpreters and install packages
such as <cite>PyInstaller</cite> in each of them.
(For more on the uses of virtualenv, see <a class="reference internal" href="#supporting-multiple-platforms">Supporting Multiple Platforms</a> below.)</p>
<p>When pip-Win is working, enter this command in its Command field
and click Run:</p>
<blockquote>
<tt class="docutils literal">venv <span class="pre">-c</span> <span class="pre">-i</span>&nbsp; <span class="pre">pyi-env-name</span></tt></blockquote>
<p>This creates a new virtual environment rooted at <tt class="docutils literal"><span class="pre">C:\Python\pyi-env-name</span></tt>
and makes it the current environment.
A new command shell
window opens in which you can run commands within this environment.
Enter the command</p>
<blockquote>
<tt class="docutils literal">pip install PyInstaller</tt></blockquote>
<p>Once it is installed, to use <cite>PyInstaller</cite>,</p>
<ul class="simple">
<li>Start pip-Win</li>
<li>In the Command field enter <tt class="docutils literal">venv <span class="pre">pyi-env-name</span></tt></li>
<li>Click Run</li>
</ul>
<p>Then you have a command shell window in which commands such as
<cite>pyinstaller</cite> execute in that Python environment.</p>
</div>
<div class="section" id="installing-in-mac-os-x">
<h2><a class="toc-backref" href="#id13">Installing in Mac&nbsp;OS&nbsp;X</a></h2>
<p><cite>PyInstaller</cite> works with the default Python 2.7 provided with current
Mac&nbsp;OS&nbsp;X installations.
However, if you plan to use a later version of Python,
or if you use any of the major packages such as
PyQt, Numpy, Matplotlib, Scipy, and the like, we strongly
recommend that you install these using either <a class="reference external" href="https://www.macports.org/">MacPorts</a> or <a class="reference external" href="http://brew.sh/">Homebrew</a>.</p>
<p><cite>PyInstaller</cite> users report fewer problems when they use a package manager
than when they attempt to install major packages individually.</p>
</div>
<div class="section" id="installing-from-the-archive">
<h2><a class="toc-backref" href="#id14">Installing from the archive</a></h2>
<p>If pip is not available, download the compressed archive from <a class="reference external" href="https://pypi.python.org/pypi/PyInstaller/">PyPI</a>.
If you are asked to test a problem using the latest development code,
download the compressed archive from the <em>develop</em> branch of
<a class="reference external" href="https://github.com/pyinstaller/pyinstaller/releases">PyInstaller Downloads</a> page.</p>
<p>Expand the archive.
Inside is a script named <tt class="docutils literal">setup.py</tt>.
Execute <tt class="docutils literal">python setup.py install</tt>
with administrator privilege to install or upgrade <cite>PyInstaller</cite>.</p>
<p>For platforms other than Windows, Linux and Mac OS, you must first
build a bootloader program for your platform: see <a class="reference internal" href="#building-the-bootloader">Building the Bootloader</a>.
After the bootloader has been created,
use <tt class="docutils literal">python setup.py install</tt> with administrator privileges
to complete the installation.</p>
</div>
<div class="section" id="verifying-the-installation">
<h2><a class="toc-backref" href="#id15">Verifying the installation</a></h2>
<p>On all platforms, the command <tt class="docutils literal">pyinstaller</tt> should now exist on the
execution path. To verify this, enter the command</p>
<blockquote>
<tt class="docutils literal">pyinstaller <span class="pre">--version</span></tt></blockquote>
<p>The result should resemble <tt class="docutils literal">3.n</tt> for a released version,
and <tt class="docutils literal"><span class="pre">3.n.dev0-xxxxxx</span></tt> for a development branch.</p>
<p>If the command is not found, make sure the execution path includes
the proper directory:</p>
<ul class="simple">
<li>Windows: <tt class="docutils literal"><span class="pre">C:\PythonXY\Scripts</span></tt> where <em>XY</em> stands for the
major and minor Python verysion number,
for example <tt class="docutils literal"><span class="pre">C:\Python34\Scripts</span></tt> for Python 3.4)</li>
<li>Linux: <tt class="docutils literal">/usr/bin/</tt></li>
<li>OS X (using the default Apple-supplied Python) <tt class="docutils literal">/usr/bin</tt></li>
<li>OS X (using Python installed by homebrew) <tt class="docutils literal">/usr/local/bin</tt></li>
<li>OS X (using Python installed by macports) <tt class="docutils literal">/opt/local/bin</tt></li>
</ul>
<p>To display the current path in Windows the command is <tt class="docutils literal">echo %path%</tt>
and in other systems, <tt class="docutils literal">echo $PATH</tt>.</p>
</div>
<div class="section" id="installed-commands">
<h2><a class="toc-backref" href="#id16">Installed commands</a></h2>
<p>The complete installation places these commands on the execution path:</p>
<ul class="simple">
<li><tt class="docutils literal">pyinstaller</tt> is the main command to build a bundled application.
See <a class="reference internal" href="#using-pyinstaller">Using PyInstaller</a>.</li>
<li><tt class="docutils literal"><span class="pre">pyi-makespec</span></tt> is used to create a spec file. See <a class="reference internal" href="#using-spec-files">Using Spec Files</a>.</li>
<li><tt class="docutils literal"><span class="pre">pyi-archive_viewer</span></tt> is used to inspect a bundled application.
See <a class="reference internal" href="#inspecting-archives">Inspecting Archives</a>.</li>
<li><tt class="docutils literal"><span class="pre">pyi-bindepend</span></tt> is used to display dependencies of an executable.
See <a class="reference internal" href="#inspecting-executables">Inspecting Executables</a>.</li>
<li><tt class="docutils literal"><span class="pre">pyi-grab_version</span></tt> is used to extract a version resource from a Windows
executable.  See <a class="reference internal" href="#capturing-windows-version-data">Capturing Windows Version Data</a>.</li>
</ul>
<p>If you do not perform a complete installation
(installing via <tt class="docutils literal">pip</tt> or executing <tt class="docutils literal">setup.py</tt>),
these commands will not be installed as commands.
However, you can still execute all the functions documented below
by running Python scripts found in the distribution folder.
The equivalent of the <tt class="docutils literal">pyinstaller</tt> command is
<em>pyinstaller-folder</em><tt class="docutils literal">/pyinstaller.py</tt>.
The other commands are found in <em>pyinstaller-folder</em> <tt class="docutils literal">/cliutils/</tt>
with meaningful names (<tt class="docutils literal">makespec.py</tt>, etc.)</p>
</div>
</div>
<div class="section" id="what-pyinstaller-does-and-how-it-does-it">
<h1><a class="toc-backref" href="#id17">What <cite>PyInstaller</cite> Does and How It Does It</a></h1>
<p>This section covers the basic ideas of <cite>PyInstaller</cite>.
These ideas apply to all platforms.
Options and special cases are covered below, under <a class="reference internal" href="#using-pyinstaller">Using PyInstaller</a>.</p>
<p><cite>PyInstaller</cite> reads a Python script written by you.
It analyzes your code to discover every other module and library
your script needs in order to execute.
Then it collects copies of all those files -- including
the active Python interpreter! -- and puts them with
your script in a single folder,
or optionally in a single executable file.</p>
<p>For the great majority of programs, this can be done with one short command,</p>
<blockquote>
pyinstaller myscript.py</blockquote>
<p>or with a few added options, for example a windowed application
as a single-file executable,</p>
<blockquote>
pyinstaller --onefile --windowed myscript.py</blockquote>
<p>You distribute the bundle as a folder or file to other people,
and they can execute
your program.
To your users, the app is self-contained.
They do not need to install any particular version of Python or any modules.
They do not need to have Python installed at all.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p>The output of  <cite>PyInstaller</cite> is specific to the active operating system
and the active version of Python.
This means that to prepare a distribution for:</p>
<blockquote>
<ul class="simple">
<li>a different OS</li>
<li>a different version of Python</li>
<li>a 32-bit or 64-bit OS</li>
</ul>
</blockquote>
<p class="last">you run <cite>PyInstaller</cite> on that OS, under that version of Python.
The Python interpreter that executes <cite>PyInstaller</cite> is part of
the bundle, and it is specific to the OS and the word size.</p>
</div>
<div class="section" id="analysis-finding-the-files-your-program-needs">
<h2><a class="toc-backref" href="#id18">Analysis: Finding the Files Your Program Needs</a></h2>
<p>What other modules and libraries does your script need in order to run?
(These are sometimes called its &quot;dependencies&quot;.)</p>
<p>To find out, <cite>PyInstaller</cite> finds all the <tt class="docutils literal">import</tt> statements
in your script.
It finds the imported modules and looks in them for <tt class="docutils literal">import</tt>
statements, and so on recursively, until it has a complete list of
modules your script may use.</p>
<p><cite>PyInstaller</cite> understands the &quot;egg&quot; distribution format often used
for Python packages.
If your script imports a module from an &quot;egg&quot;, <cite>PyInstaller</cite> adds
the egg and its dependencies to the set of needed files.</p>
<p><cite>PyInstaller</cite> also knows about many major Python packages,
including the GUI packages
<a class="reference external" href="http://www.qt-project.org">Qt</a> (imported via <a class="reference external" href="http://www.riverbankcomputing.co.uk/software/pyqt/intro">PyQt</a> or <a class="reference external" href="http://qt-project.org/wiki/About-PySide">PySide</a>), <a class="reference external" href="http://www.wxpython.org/">WxPython</a>, <a class="reference external" href="http://wiki.python.org/moin/TkInter">TkInter</a>, <a class="reference external" href="https://www.djangoproject.com/">Django</a>,
and other major packages.
For a complete list, see <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/Supported-Packages">Supported Packages</a>.</p>
<p>Some Python scripts import modules in ways that <cite>PyInstaller</cite> cannot detect:
for example, by using the <tt class="docutils literal">__import__()</tt> function with variable data,
or manipulating the <tt class="docutils literal">sys.path</tt> value at run time.
If your script requires files that <cite>PyInstaller</cite> does not know about,
you must help it:</p>
<ul class="simple">
<li>You can give additional files on the <tt class="docutils literal">pyinstaller</tt> command line.</li>
<li>You can give additional import paths on the command line.</li>
<li>You can edit the <tt class="docutils literal">myscript.spec</tt> file
that <cite>PyInstaller</cite> writes the first time you run it for your script.
In the spec file you can tell <cite>PyInstaller</cite> about code modules
that are unique to your script.</li>
<li>You can write &quot;hook&quot; files that inform <cite>PyInstaller</cite> of hidden imports.
If you create a &quot;hook&quot; for a package that other users might also use,
you can contribute your hook file to <cite>PyInstaller</cite>.</li>
</ul>
<p>If your program depends on access to certain data files,
you can tell <cite>PyInstaller</cite> to include them in the bundle as well.
You do this by modifying the spec file, an advanced topic that is
covered under <a class="reference internal" href="#using-spec-files">Using Spec Files</a>.</p>
<p>In order to locate included files at run time,
your program needs to be able to learn its path at run time
in a way that works regardless of
whether or not it is running from a bundle.
This is covered under <a class="reference internal" href="#run-time-information">Run-time Information</a>.</p>
<p><cite>PyInstaller</cite> does <em>not</em> include libraries that should exist in
any installation of this OS.
For example in Linux, it does not bundle any file
from <tt class="docutils literal">/lib</tt> or <tt class="docutils literal">/usr/lib</tt>, assuming these will be found in every system.</p>
</div>
<div class="section" id="bundling-to-one-folder">
<h2><a class="toc-backref" href="#id19">Bundling to One Folder</a></h2>
<p>When you apply <cite>PyInstaller</cite> to <tt class="docutils literal">myscript.py</tt> the default
result is a single folder named <tt class="docutils literal">myscript</tt>.
This folder contains all your script's dependencies,
and an executable file also named <tt class="docutils literal">myscript</tt>
(<tt class="docutils literal">myscript.exe</tt> in Windows).</p>
<p>You compress the folder
to <tt class="docutils literal">myscript.zip</tt> and transmit it to your users.
They install the program simply by unzipping it.
A user runs your app by
opening the folder and launching the <tt class="docutils literal">myscript</tt> executable inside it.</p>
<p>It is easy to debug problems that occur when building the app
when you use one-folder mode.
You can see exactly what files <cite>PyInstaller</cite> collected into the folder.</p>
<p>Another advantage of a one-folder bundle
is that when you change your code, as long
as it imports <cite>exactly the same set of dependencies</cite>, you could send out
only the updated <tt class="docutils literal">myscript</tt> executable.
That is typically much smaller
than the entire folder.
(If you change the script so that it imports more
or different dependencies, or if the dependencies
are upgraded, you must redistribute the whole bundle.)</p>
<p>A small disadvantage of the one-folder format is that the one folder contains
a large number of files.
Your user must find the <tt class="docutils literal">myscript</tt> executable
in a long list of names or among a big array of icons.
Also your user can create
a problem by accidentally dragging files out of the folder.</p>
</div>
<div class="section" id="how-the-one-folder-program-works">
<h2><a class="toc-backref" href="#id20">How the One-Folder Program Works</a></h2>
<p>A bundled program always starts execution in the <cite>PyInstaller</cite> bootloader.
This is the heart of the <tt class="docutils literal">myscript</tt> executable in the folder.</p>
<p>The <cite>PyInstaller</cite> bootloader is a binary
executable program for the active platform
(Windows, Linux, Mac&nbsp;OS&nbsp;X, etc.).
When the user launches your program, it is the bootloader that runs.
The bootloader creates a temporary Python environment
such that the Python interpreter will find all imported modules and
libraries in the <tt class="docutils literal">myscript</tt> folder.</p>
<p>The bootloader starts a copy of the Python interpreter
to execute your script.
Everything follows normally from there, provided
that all the necessary support files were included.</p>
<p>(This is an overview.
For more detail, see <a class="reference internal" href="#the-bootstrap-process-in-detail">The Bootstrap Process in Detail</a> below.)</p>
</div>
<div class="section" id="bundling-to-one-file">
<h2><a class="toc-backref" href="#id21">Bundling to One File</a></h2>
<p><cite>PyInstaller</cite> can bundle your script and all its dependencies into a single
executable named <tt class="docutils literal">myscript</tt> (<tt class="docutils literal">myscript.exe</tt> in Windows).</p>
<p>The advantage is that your users get something they understand,
a single executable to launch.
A disadvantage is that any related files
such as a README must be distributed separately.
Also, the single executable is a little slower to start up than
the one-folder bundle.</p>
<p>Before you attempt to bundle to one file, make sure your app
works correctly when bundled to one folder.
It is is <em>much</em> easier to diagnose problems in one-folder mode.</p>
</div>
<div class="section" id="how-the-one-file-program-works">
<h2><a class="toc-backref" href="#id22">How the One-File Program Works</a></h2>
<p>The bootloader is the heart of the one-file bundle also.
When started it creates a temporary folder
in the appropriate temp-folder location for this OS.
The folder is named <tt class="docutils literal">_MEI</tt><em>xxxxxx</em>, where <em>xxxxxx</em> is a random number.</p>
<p>The one executable file contains an embedded archive of all the Python
modules used by your script, as well as
compressed copies of any non-Python support files (e.g. <tt class="docutils literal">.so</tt> files).
The bootloader uncompresses the support files and writes copies
into the the temporary folder.
This can take a little time.
That is why a one-file app is a little slower to start
than a one-folder app.</p>
<p>After creating the temporary folder, the bootloader
proceeds exactly as for the one-folder bundle,
in the context of the temporary folder.
When the bundled code terminates,
the bootloader deletes the temporary folder.</p>
<p>(In Linux and related systems, it is possible
to mount the <tt class="docutils literal">/tmp</tt> folder with a &quot;no-execution&quot; option.
That option is not compatible with a <cite>PyInstaller</cite>
one-file bundle. It needs to execute code out of <tt class="docutils literal">/tmp</tt>.)</p>
<p>Because the program makes a temporary folder with a unique name,
you can run multiple copies of the app;
they won't interfere with each other.
However, running multiple copies is expensive in disk space because
nothing is shared.</p>
<p>The <tt class="docutils literal">_MEI</tt><em>xxxxxx</em> folder is not removed if the program crashes
or is killed (kill -9 on Unix, killed by the Task Manager on Windows,
&quot;Force Quit&quot; on Mac OS).
Thus if your app crashes frequently, your users will lose disk space to
multiple <tt class="docutils literal">_MEI</tt><em>xxxxxx</em> temporary folders.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Do <em>not</em> give administrator privileges to a one-file executable
(setuid root in Unix/Linux, or the &quot;Run this program as an administrator&quot;
property in Windows 7).
There is an unlikely but not impossible way in which a malicious attacker could
corrupt one of the shared libraries in the temp folder
while the bootloader is preparing it.
Distribute a privileged program in one-folder mode instead.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Applications that use <cite>os.setuid()</cite> may encounter permissions errors.
The temporary folder where the bundled app runs may not being readable
after <cite>setuid</cite> is called. If your script needs to
call <cite>setuid</cite>, it may be better to use one-folder mode
so as to have more control over the permissions on its files.</p>
</div>
</div>
<div class="section" id="using-a-console-window">
<h2><a class="toc-backref" href="#id23">Using a Console Window</a></h2>
<p>By default the bootloader creates a command-line console
(a terminal window in Linux and Mac OS, a command window in Windows).
It gives this window to the Python interpreter for its standard input and output.
Your script's use of <tt class="docutils literal">print</tt> and <tt class="docutils literal">input()</tt> are directed here.
Error messages from Python and default logging output
also appear in the console window.</p>
<p>An option for Windows and Mac OS is to tell <cite>PyInstaller</cite> to not provide a console window.
The bootloader starts Python with no target for standard output or input.
Do this when your script has a graphical interface for user input and can properly
report its own diagnostics.</p>
</div>
<div class="section" id="hiding-the-source-code">
<h2><a class="toc-backref" href="#id24">Hiding the Source Code</a></h2>
<p>The bundled app does not include any source code.
However, <cite>PyInstaller</cite> bundles compiled Python scripts (<tt class="docutils literal">.pyc</tt> files).
These could in principle be decompiled to reveal the logic of
your code.</p>
<p>If you want to hide your source code more thoroughly, one possible option
is to compile some of your modules with <a class="reference external" href="http://www.cython.org/">Cython</a>.
Using Cython you can convert Python modules into C and compile
the C to machine language.
<cite>PyInstaller</cite> can follow import statements that refer to
Cython C object modules and bundle them.</p>
<p>Additionally, Python bytecode can be obfuscated with AES256 by specifying
an encryption key on PyInstaller's command line. Please note that it is still
very easy to extract the key and get back the original bytecode, but it
should prevent most forms of &quot;casual&quot; tampering.</p>
</div>
</div>
<div class="section" id="using-pyinstaller">
<h1><a class="toc-backref" href="#id25">Using PyInstaller</a></h1>
<p>The syntax of the <tt class="docutils literal">pyinstaller</tt> command is:</p>
<blockquote>
<tt class="docutils literal">pyinstaller</tt> [<em>options</em>] <em>script</em> [<em>script</em> ...] | <em>specfile</em></blockquote>
<p>In the most simple case,
set the current directory to the location of your program <tt class="docutils literal">myscript.py</tt>
and execute:</p>
<pre class="literal-block">
pyinstaller myscript.py
</pre>
<p><cite>PyInstaller</cite> analyzes <tt class="docutils literal">myscript.py</tt> and:</p>
<ul class="simple">
<li>Writes <tt class="docutils literal">myscript.spec</tt> in the same folder as the script.</li>
<li>Creates a folder <tt class="docutils literal">build</tt> in the same folder as the script if it does not exist.</li>
<li>Writes some log files and working files in the <tt class="docutils literal">build</tt> folder.</li>
<li>Creates a folder <tt class="docutils literal">dist</tt> in the same folder as the script if it does not exist.</li>
<li>Writes the <tt class="docutils literal">myscript</tt> executable folder in the <tt class="docutils literal">dist</tt> folder.</li>
</ul>
<p>In the <tt class="docutils literal">dist</tt> folder you find the bundled app you distribute to your users.</p>
<p>Normally you name one script on the command line.
If you name more, all are analyzed and included in the output.
However, the first script named supplies the name for the
spec file and for the executable folder or file.
Its code is the first to execute at run-time.</p>
<p>For certain uses you may edit the contents of <tt class="docutils literal">myscript.spec</tt>
(described under <a class="reference internal" href="#using-spec-files">Using Spec Files</a>).
After you do this, you name the spec file to <cite>PyInstaller</cite> instead of the script:</p>
<blockquote>
<tt class="docutils literal">pyinstaller myscript.spec</tt></blockquote>
<p>You may give a path to the script or spec file, for example</p>
<blockquote>
<tt class="docutils literal">pyinstaller</tt> <cite>options...</cite> <tt class="docutils literal">~/myproject/source/myscript.py</tt></blockquote>
<p>or, on Windows,</p>
<blockquote>
<tt class="docutils literal">pyinstaller <span class="pre">&quot;C:\Documents</span> and Settings\project\myscript.spec&quot;</tt></blockquote>
<div class="section" id="options">
<h2><a class="toc-backref" href="#id26">Options</a></h2>
<div class="section" id="general-options">
<h3><a class="toc-backref" href="#id27">General Options</a></h3>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
<td>show this help message and exit</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></td>
<td>Show program version info and exit.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--distpath <var>DIR</var></span></kbd></td>
<td>Where to put the bundled app (default: ./dist)</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--workpath <var>WORKPATH</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Where to put all the temporary work files, .log, .pyz
and etc. (default: ./build)</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-y</span>, <span class="option">--noconfirm</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Replace output directory (default:
SPECPATH/dist/SPECNAME) without asking for
confirmation</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--upx-dir <var>UPX_DIR</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Path to UPX utility (default: search the execution
path)</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-a</span>, <span class="option">--ascii</span></kbd></td>
<td>Do not include unicode encoding support (default:
included if available)</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--clean</span></kbd></td>
<td>Clean PyInstaller cache and remove temporary files
before building.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--log-level <var>LEVEL</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Amount of detail in build-time console messages. LEVEL
may be one of DEBUG, INFO, WARN, ERROR, CRITICAL
(default: INFO).</td></tr>
</tbody>
</table>
</div>
<div class="section" id="what-to-generate">
<h3><a class="toc-backref" href="#id28">What to generate</a></h3>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-D</span>, <span class="option">--onedir</span></kbd></td>
<td>Create a one-folder bundle containing an executable
(default)</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-F</span>, <span class="option">--onefile</span></kbd></td>
<td>Create a one-file bundled executable.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--specpath <var>DIR</var></span></kbd></td>
<td>Folder to store the generated spec file (default:
current directory)</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-n <var>NAME</var></span>, <span class="option">--name <var>NAME</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Name to assign to the bundled app and spec file
(default: first script's basename)</td></tr>
</tbody>
</table>
</div>
<div class="section" id="what-to-bundle-where-to-search">
<h3><a class="toc-backref" href="#id29">What to bundle, where to search</a></h3>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-p <var>DIR</var></span>, <span class="option">--paths <var>DIR</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>A path to search for imports (like using PYTHONPATH).
Multiple paths are allowed, separated by ':', or use
this option multiple times</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--hidden-import <var>MODULENAME</var></span>, <span class="option">--hiddenimport <var>MODULENAME</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Name an import not visible in the code of the
script(s). This option can be used multiple times.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--additional-hooks-dir <var>HOOKSPATH</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>An additional path to search for hooks. This option
can be used multiple times.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--runtime-hook <var>RUNTIME_HOOKS</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Path to a custom runtime hook file. A runtime hook is
code that is bundled with the executable and is
executed before any other code or module to set up
special features of the runtime environment. This
option can be used multiple times.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--exclude-module <var>EXCLUDES</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Optional module or package (his Python names, not path
names) that will be ignored (as though it was not
found). This option can be used multiple times.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--key <var>KEY</var></span></kbd></td>
<td>The key used to encrypt Python bytecode.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="how-to-generate">
<h3><a class="toc-backref" href="#id30">How to generate</a></h3>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-d</span>, <span class="option">--debug</span></kbd></td>
<td>Tell the bootloader to issue progress messages while
initializing and starting the bundled app. Used to
diagnose problems with missing imports.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-s</span>, <span class="option">--strip</span></kbd></td>
<td>Apply a symbol-table strip to the executable and
shared libs (not recommended for Windows)</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--noupx</span></kbd></td>
<td>Do not use UPX even if it is available (works
differently between Windows and *nix)</td></tr>
</tbody>
</table>
</div>
<div class="section" id="windows-and-mac-os-x-specific-options">
<h3><a class="toc-backref" href="#id31">Windows and Mac OS X specific options</a></h3>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-c</span>, <span class="option">--console</span>, <span class="option">--nowindowed</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Open a console window for standard i/o (default)</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-w</span>, <span class="option">--windowed</span>, <span class="option">--noconsole</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Windows and Mac OS X: do not provide a console window
for standard i/o. On Mac OS X this also triggers
building an OS X .app bundle. This option is ignored
in *NIX systems.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-i <var>&lt;FILE.ico or FILE.exe,ID or FILE.icns&gt;</var></span>, <span class="option">--icon <var>&lt;FILE.ico or FILE.exe,ID or FILE.icns&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>FILE.ico: apply that icon to a Windows executable.
FILE.exe,ID, extract the icon with ID from an exe.
FILE.icns: apply the icon to the .app bundle on Mac OS
X</td></tr>
</tbody>
</table>
</div>
<div class="section" id="windows-specific-options">
<h3><a class="toc-backref" href="#id32">Windows specific options</a></h3>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--version-file <var>FILE</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>add a version resource from FILE to the exe</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-m <var>&lt;FILE or XML&gt;</var></span>, <span class="option">--manifest <var>&lt;FILE or XML&gt;</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>add manifest FILE or XML to the exe</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-r <var>RESOURCE</var></span>, <span class="option">--resource <var>RESOURCE</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Add or update a resource to a Windows executable. The
RESOURCE is one to four items,
FILE[,TYPE[,NAME[,LANGUAGE]]]. FILE can be a data file
or an exe/dll. For data files, at least TYPE and NAME
must be specified. LANGUAGE defaults to 0 or may be
specified as wildcard * to update all resources of the
given TYPE and NAME. For exe/dll files, all resources
from FILE will be added/updated to the final
executable if TYPE, NAME and LANGUAGE are omitted or
specified as wildcard *.This option can be used
multiple times.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--uac-admin</span></kbd></td>
<td>Using this option creates a Manifest which will
request elevation upon application restart.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--uac-uiaccess</span></kbd></td>
<td>Using this option allows an elevated application to
work with Remote Desktop.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="windows-side-by-side-assembly-searching-options-advanced">
<h3><a class="toc-backref" href="#id33">Windows Side-by-side Assembly searching options (advanced)</a></h3>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--win-private-assemblies</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Any Shared Assemblies bundled into the application
will be changed into Private Assemblies. This means
the exact versions of these assemblies will always be
used, and any newer versions installed on user
machines at the system level will be ignored.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--win-no-prefer-redirects</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>While searching for Shared or Private Assemblies to
bundle into the application, PyInstaller will prefer
not to follow policies that redirect to newer
versions, and will try to bundle the exact versions of
the assembly.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="mac-os-x-specific-options">
<h3><a class="toc-backref" href="#id34">Mac OS X specific options</a></h3>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--osx-bundle-identifier <var>BUNDLE_IDENTIFIER</var></span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Mac OS X .app bundle identifier is used as the default
unique program name for code signing purposes. The
usual form is a hierarchical name in reverse DNS
notation. For example:
com.mycompany.department.appname (default: first
script's basename)</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="shortening-the-command">
<h2><a class="toc-backref" href="#id35">Shortening the Command</a></h2>
<p>Because of its numerous options, a full <tt class="docutils literal">pyinstaller</tt> command
can become very long.
You will run the same command again and again as you develop
your script.
You can put the command in a shell script or batch file,
using line continuations to make it readable.
For example, in Linux:</p>
<pre class="literal-block">
pyinstaller --noconfirm --log-level=WARN \
    --onefile --nowindow \
    --hidden-import=secret1 \
    --hidden-import=secret2 \
    --upx-dir=/usr/local/share/ \
    myscript.spec
</pre>
<p>Or in Windows, use the little-known BAT file line continuation:</p>
<pre class="literal-block">
pyinstaller --noconfirm --log-level=WARN ^
    --onefile --nowindow ^
    --hidden-import=secret1 ^
    --hidden-import=secret2 ^
    --icon-file=..\MLNMFLCN.ICO ^
    myscript.spec
</pre>
</div>
<div class="section" id="using-upx">
<h2><a class="toc-backref" href="#id36">Using UPX</a></h2>
<p><a class="reference external" href="http://upx.sourceforge.net/">UPX</a> is a free utility available for most operating systems.
UPX compresses executable files and libraries, making them smaller,
sometimes much smaller.
UPX is available for most operating systems and can compress
a large number of executable file formats.
See the <a class="reference external" href="http://upx.sourceforge.net/">UPX</a> home page for downloads, and for the list of
supported executable formats.
Development of UPX appears to have ended in September 2013,
at which time it supported most executable formats except for
64-bit binaries for Mac&nbsp;OS&nbsp;X.
UPX has no effect on those.</p>
<p>A compressed executable program is wrapped in UPX
startup code that dynamically decompresses the program
when the program is launched.
After it has been decompressed, the program runs normally.
In the case of a <cite>PyInstaller</cite> one-file executable that has
been UPX-compressed, the full execution sequence is:</p>
<ul class="simple">
<li>The compressed program start up in the UPX decompressor code.</li>
<li>After decompression, the program executes the <cite>PyInstaller</cite> bootloader,
which creates a temporary environment for Python.</li>
<li>The Python interpreter executes your script.</li>
</ul>
<p><cite>PyInstaller</cite> looks for UPX on the execution path
or the path specified with the <tt class="docutils literal"><span class="pre">--upx-dir</span></tt> option.
If UPX exists, <cite>PyInstaller</cite> applies it to the final executable,
unless the <tt class="docutils literal"><span class="pre">--noupx</span></tt> option was given.
UPX has been used with <cite>PyInstaller</cite> output often, usually with no problems.</p>
</div>
<div class="section" id="encrypting-python-bytecode">
<h2><a class="toc-backref" href="#id37">Encrypting Python Bytecode</a></h2>
<p>To encrypt the Python bytecode modules stored in the bundle,
pass the <tt class="docutils literal"><span class="pre">--key=</span></tt><em>key-string</em>  argument on
the command line.</p>
<p>For this to work, you must have the <a class="reference external" href="https://pypi.python.org/pypi/pycrypto/">PyCrypto</a>
module installed.
The <em>key-string</em> is a string of 16 characters which is used to
encrypt each file of Python byte-code before it is stored in
the archive inside the executable file.</p>
</div>
<div class="section" id="supporting-multiple-platforms">
<h2><a class="toc-backref" href="#id38">Supporting Multiple Platforms</a></h2>
<p>If you distribute your application for only one combination of OS and Python,
just install <cite>PyInstaller</cite> like any other package and use it in your
normal development setup.</p>
<div class="section" id="supporting-multiple-python-environments">
<h3><a class="toc-backref" href="#id39">Supporting Multiple Python Environments</a></h3>
<p>When you need to bundle your application within one OS
but for different versions of Python and support libraries -- for example,
a Python 3 version and a Python 2.7 version;
or a supported version that uses Qt4 and a development version that uses Qt5 --
we recommend you use <a class="reference external" href="http://www.virtualenv.org/">virtualenv</a>.
With virtualenv you can maintain different combinations of Python
and installed packages, and switch from one combination to another easily.
(If you work only with Python 3.4 and later, the built-in script <a class="reference external" href="https://docs.python.org/3.4/library/venv.html">pyvenv</a>
does the same job.)</p>
<ul class="simple">
<li>Use virtualenv to create as many different development environments as you need,
each with its unique combination of Python and installed packages.</li>
<li>Install <cite>PyInstaller</cite> in each environment.</li>
<li>Use <cite>PyInstaller</cite> to build your application in each environment.</li>
</ul>
<p>Note that when using virtualenv, the path to the <cite>PyInstaller</cite> commands is:</p>
<ul class="simple">
<li>Windows: ENV_ROOT\Scripts</li>
<li>Others:  ENV_ROOT/bin</li>
</ul>
<p>Under Windows, the <a class="reference external" href="https://sites.google.com/site/pydatalog/python/pip-for-windows">pip-Win</a> package installs virtualenv and makes it
especially easy to set up different environments and switch between them.
Under Linux and Mac OS, you switch environments at the command line.</p>
</div>
<div class="section" id="supporting-multiple-operating-systems">
<h3><a class="toc-backref" href="#id40">Supporting Multiple Operating Systems</a></h3>
<p>If you need to distribute your application for more than one OS,
for example both Windows and Mac&nbsp;OS&nbsp;X, you must install <cite>PyInstaller</cite>
on each platform and bundle your app separately on each.</p>
<p>You can do this from a single machine using virtualization.
The free <a class="reference external" href="https://www.virtualbox.org">virtualBox</a> or the paid <a class="reference external" href="http://www.vmware.com/solutions/desktop/">VMWare</a> and <a class="reference external" href="http://www.parallels.com/">Parallels</a>
allow you to run another complete operating system as a &quot;guest&quot;.
You set up a virtual machine for each &quot;guest&quot; OS.
In it you install
Python, the support packages your application needs, and PyInstaller.</p>
<p>The <a class="reference external" href="https://www.dropbox.com/home">Dropbox</a> system is useful with virtual machines.
Install a Dropbox client in each virtual machine, all linked to your Dropbox account.
Keep a single copy of your script(s) in a Dropbox folder.
Then on any virtual machine you can run <cite>PyInstaller</cite> thus:</p>
<pre class="literal-block">
cd ~/Dropbox/project_folder/src # Linux, Mac -- Windows similar
rm *.pyc # get rid of modules compiled by another Python
pyinstaller --workpath=path-to-local-temp-folder  \
            --distpath=path-to-local-dist-folder  \
            ...other options as required...       \
            ./myscript.py
</pre>
<p><cite>PyInstaller</cite> reads scripts from the common Dropbox folder,
but writes its work files and the bundled app in folders that
are local to the virtual machine.</p>
<p>If you share the same home directory on multiple platforms, for
example Linux and OS X, you will need to set the PYINSTALLER_CONFIG_DIR
environment variable to different values on each platform otherwise
PyInstaller may cache files for one platform and use them on the other
platform, as by default it uses a subdirectory of your home directory
as its cache location.</p>
<p>It is said to be possible to cross-develop for Windows under Linux
using the free <a class="reference external" href="http://www.winehq.org/">Wine</a> environment.
Further details are needed, see <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/How-to-Contribute">How to Contribute</a>.</p>
</div>
</div>
<div class="section" id="making-linux-apps-forward-compatible">
<h2><a class="toc-backref" href="#id41">Making Linux Apps Forward-Compatible</a></h2>
<p>Under Linux, <cite>PyInstaller</cite> does not bundle <tt class="docutils literal">libc</tt>
(the C standard library, usually <tt class="docutils literal">glibc</tt>, the Gnu version) with the app.
Instead, the app expects to link dynamically to the <tt class="docutils literal">libc</tt> from the
local OS where it runs.
The interface between any app and <tt class="docutils literal">libc</tt> is forward compatible to
newer releases, but it is not backward compatible to older releases.</p>
<p>For this reason, if you bundle your app on the current version of Linux,
it may fail to execute (typically with a runtime dynamic link error) if
it is executed on an older version of Linux.</p>
<p>The solution is to always build your app on the <em>oldest</em> version of
Linux you mean to support.
It should continue to work with the <tt class="docutils literal">libc</tt> found on newer versions.</p>
<p>The Linux standard libraries such as <tt class="docutils literal">glibc</tt> are distributed in 64-bit
and 32-bit versions, and these are not compatible.
As a result you cannot bundle your app on a 32-bit system and run it
on a 64-bit installation, nor vice-versa.
You must make a unique version of the app for each word-length supported.</p>
</div>
<div class="section" id="capturing-windows-version-data">
<h2><a class="toc-backref" href="#id42">Capturing Windows Version Data</a></h2>
<p>A Windows app may require a Version resource file.
A Version resource contains a group of data structures,
some containing binary integers and some containing strings,
that describe the properties of the executable.
For details see the Microsoft <a class="reference external" href="http://msdn.microsoft.com/en-us/library/ff468916(v=vs.85).aspx">Version Information Structures</a> page.</p>
<p>Version resources are complex and
some elements are optional, others required.
When you view the version tab of a Properties dialog,
there's no simple relationship between
the data displayed and the structure of the resource.
For this reason <cite>PyInstaller</cite> includes the <tt class="docutils literal"><span class="pre">pyi-grab_version</span></tt> command.
It is invoked with the full path name of any Windows executable
that has a Version resource:</p>
<blockquote>
<tt class="docutils literal"><span class="pre">pyi-grab_version</span></tt> <em>executable_with_version_resource</em></blockquote>
<p>The command writes text that represents
a Version resource in readable form to standard output.
You can copy it from the console window or redirect it to a file.
Then you can edit the version information to adapt it to your program.
Using <tt class="docutils literal"><span class="pre">pyi-grab_version</span></tt> you can find an executable that displays the kind of
information you want, copy its resource data, and modify it to suit your package.</p>
<p>The version text file is encoded UTF-8 and may contain non-ASCII characters.
(Unicode characters are allowed in Version resource string fields.)
Be sure to edit and save the text file in UTF-8 unless you are
certain it contains only ASCII string values.</p>
<p>Your edited version text file can be given with the <tt class="docutils literal"><span class="pre">--version-file=</span></tt>
option to <tt class="docutils literal">pyinstaller</tt> or <tt class="docutils literal"><span class="pre">pyi-makespec</span></tt>.
The text data is converted to a Version resource and
installed in the bundled app.</p>
<p>In a Version resource there are two 64-bit binary values,
<tt class="docutils literal">FileVersion</tt> and <tt class="docutils literal">ProductVersion</tt>.
In the version text file these are given as four-element tuples,
for example:</p>
<pre class="literal-block">
filevers=(2, 0, 4, 0),
prodvers=(2, 0, 4, 0),
</pre>
<p>The elements of each tuple represent 16-bit values
from most-significant to least-significant.
For example the value <tt class="docutils literal">(2, 0, 4, 0)</tt> resolves to
<tt class="docutils literal">0002000000040000</tt> in hex.</p>
<p>You can also install a Version resource from a text file after
the bundled app has been created, using the <tt class="docutils literal">set_version</tt> command:</p>
<blockquote>
<tt class="docutils literal">set_version</tt> <em>version_text_file</em> <em>executable_file</em></blockquote>
<p>The <tt class="docutils literal">set_version</tt> utility reads a version text file as written
by <tt class="docutils literal"><span class="pre">pyi-grab_version</span></tt>, converts it to a Version resource,
and installs that resource in the <em>executable_file</em> specified.</p>
<p>For advanced uses, examine a version text file as written by  <tt class="docutils literal"><span class="pre">pyi-grab_version</span></tt>.
You find it is Python code that creates a <tt class="docutils literal">VSVersionInfo</tt> object.
The class definition for <tt class="docutils literal">VSVersionInfo</tt> is found in
<tt class="docutils literal">utils/win32/versioninfo.py</tt> in the <cite>PyInstaller</cite> distribution folder.
You can write a program that imports <tt class="docutils literal">versioninfo</tt>.
In that program you can <tt class="docutils literal">eval</tt>
the contents of a version info text file to produce a
<tt class="docutils literal">VSVersionInfo</tt> object.
You can use the <tt class="docutils literal">.toRaw()</tt> method of that object to
produce a Version resource in binary form.
Or you can apply the <tt class="docutils literal">unicode()</tt> function to the object
to reproduce the version text file.</p>
</div>
<div class="section" id="building-mac-os-x-app-bundles">
<h2><a class="toc-backref" href="#id43">Building Mac&nbsp;OS&nbsp;X App Bundles</a></h2>
<p>If you specify only <tt class="docutils literal"><span class="pre">--onefile</span></tt> under Mac&nbsp;OS&nbsp;X, the output
in <tt class="docutils literal">dist</tt> is a UNIX executable
<tt class="docutils literal">myscript</tt>.
It can be executed from a Terminal command line.
Standard input and output work as normal through the Terminal window.</p>
<p>If you also specify <tt class="docutils literal"><span class="pre">--windowed</span></tt>, the <tt class="docutils literal">dist</tt> folder contains
two outputs: the UNIX executable <tt class="docutils literal">myscript</tt>
and also an OS X application named <tt class="docutils literal">myscript.app</tt>.</p>
<p>As you probably know, an application is a special type of folder.
The one built by <cite>PyInstaller</cite> contains a folder always named <tt class="docutils literal">Contents</tt>.
It contains:</p>
<blockquote>
<ul class="simple">
<li>A folder <tt class="docutils literal">Frameworks</tt> which is empty.</li>
<li>A folder <tt class="docutils literal">MacOS</tt> that contains a copy of the same <tt class="docutils literal">myscript</tt> UNIX executable.</li>
<li>A folder <tt class="docutils literal">Resources</tt> that contains an icon file.</li>
<li>A file <tt class="docutils literal">Info.plist</tt> that describes the app.</li>
</ul>
</blockquote>
<p><cite>PyInstaller</cite> builds minimal versions of these elements.</p>
<p>Use the <tt class="docutils literal"><span class="pre">osx-bundle-identifier=</span></tt> argument to add a bundle identifier.
This becomes the <tt class="docutils literal">CFBundleIdentifier</tt> used in code-signing
(see the <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/Recipe-OSX-Code-Signing">PyInstaller code signing recipe</a>
and for more detail, the <a class="reference external" href="https://developer.apple.com/library/mac/technotes/tn2206/_index.html">Apple code signing overview</a> technical note).</p>
<p>Use the <tt class="docutils literal">icon=</tt> argument to specify a custom icon for the application.
(If you do not specify an icon file, <cite>PyInstaller</cite> supplies a
file <tt class="docutils literal"><span class="pre">icon-windowed.icns</span></tt> with the <cite>PyInstaller</cite> logo.)</p>
<p>You can add items to the <tt class="docutils literal">Info.plist</tt> by editing the spec file;
see <a class="reference internal" href="#spec-file-options-for-a-mac-os-x-bundle">Spec File Options for a Mac&nbsp;OS&nbsp;X Bundle</a> below.</p>
<div class="section" id="making-mac-os-x-apps-forward-compatible">
<h3><a class="toc-backref" href="#id44">Making Mac&nbsp;OS&nbsp;X apps Forward-Compatible</a></h3>
<p>In Mac&nbsp;OS&nbsp;X, components from one version of the OS are usually compatible
with later versions, but they may not work with earlier versions.</p>
<p>The only way to be certain your app supports an older version of Mac&nbsp;OS&nbsp;X
is to run PyInstaller in the oldest version of the OS you need to support.</p>
<p>For example, to be sure of compatibility with &quot;Snow Leopard&quot; (10.6)
and later versions, you should execute PyInstaller in that environment.
You would create a copy of Mac&nbsp;OS&nbsp;X 10.6, typically in a virtual machine.
In it, install the desired level of Python
(the default Python in Snow Leopard was 2.6, which PyInstaller no longer supports),
and install <cite>PyInstaller</cite>, your source, and all its dependencies.
Then build your app in that environment.
It should be compatible with later versions of Mac OS X.</p>
</div>
<div class="section" id="building-32-bit-apps-in-mac-os-x">
<h3><a class="toc-backref" href="#id45">Building 32-bit Apps in Mac&nbsp;OS&nbsp;X</a></h3>
<p>Older versions of Mac&nbsp;OS&nbsp;X supported both 32-bit and 64-bit executables.
PyInstaller builds an app using the the word-length of the Python used to execute it.
That will typically be a 64-bit version of Python,
resulting in a 64-bit executable.
To create a 32-bit executable, run PyInstaller under a 32-bit Python.</p>
<p>Python as installed in OS X will usually be executable in either 64- or 32-bit mode.
To verify this, apply the <tt class="docutils literal">file</tt> command to the Python executable:</p>
<pre class="literal-block">
$ file /usr/local/bin/python3
/usr/local/bin/python3: Mach-O universal binary with 2 architectures
/usr/local/bin/python3 (for architecture i386):     Mach-O executable i386
/usr/local/bin/python3 (for architecture x86_64):   Mach-O 64-bit executable x86_64
</pre>
<p>The OS chooses which architecture to run, and typically defaults to 64-bit.
You can force the use of either architecture by name using the <tt class="docutils literal">arch</tt> command:</p>
<pre class="literal-block">
$ /usr/local/bin/python3
Python 3.4.2 (v3.4.2:ab2c023a9432, Oct  5 2014, 20:42:22)
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type &quot;help&quot;, &quot;copyright&quot;, &quot;credits&quot; or &quot;license&quot; for more information.
&gt;&gt;&gt; import sys; sys.maxsize
9223372036854775807

$ arch -i386 /usr/local/bin/python3
Python 3.4.2 (v3.4.2:ab2c023a9432, Oct  5 2014, 20:42:22)
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type &quot;help&quot;, &quot;copyright&quot;, &quot;credits&quot; or &quot;license&quot; for more information.
&gt;&gt;&gt; import sys; sys.maxsize
2147483647
</pre>
<p>Apple's default <tt class="docutils literal">/usr/bin/python</tt> may circumvent the <tt class="docutils literal">arch</tt>
specification and run 64-bit regardless.
(That is not the case if you apply <tt class="docutils literal">arch</tt> to a specific version
such as <tt class="docutils literal">/usr/bin/python2.7</tt>.)
To make sure of running 32-bit in all cases, set the following environment variable:</p>
<pre class="literal-block">
VERSIONER_PYTHON_PREFER_32_BIT=yes
arch -i386 /usr/bin/python pyinstaller --clean -F -w myscript.py
</pre>
</div>
<div class="section" id="getting-the-opened-document-names">
<h3><a class="toc-backref" href="#id46">Getting the Opened Document Names</a></h3>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Support for OpenDocument events is broken in <cite>PyInstaller</cite> 3.0
owing to code changes needed in the bootloader to support current
versions of Mac&nbsp;OS&nbsp;X.
Do not attempt to use this feature until it has been fixed.
If this feature is important to you, follow and comment on
the status of <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/issues/1309">PyInstaller Issue #1309</a>.</p>
</div>
<p>When a user double-clicks a document of a type your application
supports, or when a user drags a document icon and drops it
on your application's icon, Mac&nbsp;OS&nbsp;X launches your application
and provides the name(s) of the opened document(s) in the
form of an OpenDocument AppleEvent.
This AppleEvent is received by the bootloader
before your code has started executing.</p>
<p>The bootloader gets the names of opened documents from
the OpenDocument event and encodes them into the <tt class="docutils literal">argv</tt>
string before starting your code.
Thus your code can query <tt class="docutils literal">sys.argv</tt> to get the names
of documents that should be opened at startup.</p>
<p>OpenDocument is the only AppleEvent the bootloader handles.
If you want to handle other events, or events that
are delivered after the program has launched, you must
set up the appropriate handlers.</p>
</div>
</div>
</div>
<div class="section" id="run-time-information">
<h1><a class="toc-backref" href="#id47">Run-time Information</a></h1>
<p>Your app should run in a bundle exactly as it does when run from source.
However, you may need to learn at run-time
whether the app is running from source, or is &quot;frozen&quot; (bundled).
For example, you might have
data files that are normally found based on a module's <tt class="docutils literal">__file__</tt> attribute.
That will not work when the code is bundled.</p>
<p>The <cite>PyInstaller</cite> bootloader adds the name <tt class="docutils literal">frozen</tt> to the <tt class="docutils literal">sys</tt> module.
So the test for &quot;are we bundled?&quot; is:</p>
<pre class="literal-block">
import sys
if getattr( sys, 'frozen', False ) :
        # running in a bundle
else :
        # running live
</pre>
<p>When your app is running, it may need to access data files in any of
three general locations:</p>
<ul class="simple">
<li>Files that were bundled with it (see <a class="reference internal" href="#adding-data-files">Adding Data Files</a>).</li>
<li>Files the user has placed with the app bundle, say in the same folder.</li>
<li>Files in the user's current working directory.</li>
</ul>
<p>The program has access to several path variables for these uses.</p>
<div class="section" id="using-file-and-sys-meipass">
<h2><a class="toc-backref" href="#id48">Using <tt class="docutils literal">__file__</tt> and <tt class="docutils literal">sys._MEIPASS</tt></a></h2>
<p>When your program is not frozen, the standard Python
variable <tt class="docutils literal">__file__</tt> is the full path to the script now executing.
When a bundled app starts up,
the bootloader sets the <tt class="docutils literal">sys.frozen</tt> attribute
and stores the absolute path to the bundle folder in <tt class="docutils literal">sys._MEIPASS</tt>.
For a one-folder bundle, this is the path to that folder,
wherever the user may have put it.
For a one-file bundle, this is the path to the <tt class="docutils literal">_MEIxxxxxx</tt> temporary folder
created by the bootloader (see <a class="reference internal" href="#how-the-one-file-program-works">How the One-File Program Works</a>).</p>
</div>
<div class="section" id="using-sys-executable-and-sys-argv-0">
<h2><a class="toc-backref" href="#id49">Using <tt class="docutils literal">sys.executable</tt> and <tt class="docutils literal">sys.argv[0]</tt></a></h2>
<p>When a normal Python script runs, <tt class="docutils literal">sys.executable</tt> is the path to the
program that was executed, namely, the Python interpreter.
In a frozen app, <tt class="docutils literal">sys.executable</tt> is also the path to the
program that was executed, but that is not Python;
it is the bootloader in either the one-file app
or the executable in the one-folder app.
This gives you a reliable way to locate the frozen executable the user
actually launched.</p>
<p>The value of <tt class="docutils literal">sys.argv[0]</tt> is the name or relative path that was
used in the user's command.
It may be a relative path or an absolute path depending
on the platform and how the app was launched.</p>
<p>If the user launches the app by way of a symbolic link,
<tt class="docutils literal">sys.argv[0]</tt> uses that symbolic name,
while <tt class="docutils literal">sys.executable</tt> is the actual path to the executable.
Sometimes the same app is linked under different names
and is expected to behave differently depending on the name that is
used to launch it.
For this case, you would test <tt class="docutils literal">os.path.basename(sys.argv[0])</tt></p>
<p>On the other hand, sometimes the user is told to store the executable
in the same folder as the files it will operate on,
for example a music player that should be stored in the same folder
as the audio files it will play.
For this case, you would use <tt class="docutils literal">os.path.dirname(sys.executable)</tt>.</p>
<p>The following small program explores some of these possibilities.
Save it as <tt class="docutils literal">directories.py</tt>.
Execute it as a Python script,
then bundled as a one-folder app.
Then bundle it as a one-file app and launch it directly and also via a
symbolic link:</p>
<pre class="literal-block">
#!/usr/bin/python3
import sys, os
frozen = 'not'
if getattr(sys, 'frozen', False):
        # we are running in a bundle
        frozen = 'ever so'
        bundle_dir = sys._MEIPASS
else:
        # we are running in a normal Python environment
        bundle_dir = os.path.dirname(os.path.abspath(__file__))
print( 'we are',frozen,'frozen')
print( 'bundle dir is', bundle_dir )
print( 'sys.argv[0] is', sys.argv[0] )
print( 'sys.executable is', sys.executable )
print( 'os.getcwd is', os.getcwd() )
</pre>
</div>
</div>
<div class="section" id="using-spec-files">
<h1><a class="toc-backref" href="#id50">Using Spec Files</a></h1>
<p>When you execute</p>
<blockquote>
<tt class="docutils literal">pyinstaller</tt> <em>options</em>.. <tt class="docutils literal">myscript.py</tt></blockquote>
<p>the first thing <cite>PyInstaller</cite> does is to build a spec (specification) file
<tt class="docutils literal">myscript.spec</tt>.
That file is stored in the <tt class="docutils literal"><span class="pre">--specpath=</span></tt> directory,
by default the current directory.</p>
<p>The spec file tells <cite>PyInstaller</cite> how to process your script.
It encodes the script names and most of the options
you give to the <tt class="docutils literal">pyinstaller</tt> command.
The spec file is actually executable Python code.
<cite>PyInstaller</cite> builds the app by executing the contents of the spec file.</p>
<p>For many uses of <cite>PyInstaller</cite> you do not need to examine or modify the spec file.
It is usually enough to
give all the needed information (such as hidden imports)
as options to the <tt class="docutils literal">pyinstaller</tt> command and let it run.</p>
<p>There are four cases where it is useful to modify the spec file:</p>
<ul class="simple">
<li>When you want to bundle data files with the app.</li>
<li>When you want to include run-time libraries (<tt class="docutils literal">.dll</tt> or <tt class="docutils literal">.so</tt> files) that
<cite>PyInstaller</cite> does not know about from any other source.</li>
<li>When you want to add Python run-time options to the executable.</li>
<li>When you want to create a multiprogram bundle with merged common modules.</li>
</ul>
<p>These uses are covered in topics below.</p>
<p>You create a spec file using this command:</p>
<blockquote>
<tt class="docutils literal"><span class="pre">pyi-makespec</span></tt> <em>options</em> <em>name</em><tt class="docutils literal">.py</tt> [<em>other scripts</em> ...]</blockquote>
<p>The <em>options</em> are the same options documented above
for the <tt class="docutils literal">pyinstaller</tt> command.
This command creates the <em>name</em><tt class="docutils literal">.spec</tt> file but does not
go on to build the executable.</p>
<p>After you have created a spec file and modified it as necessary,
you build the application by passing the spec file to the <tt class="docutils literal">pyinstaller</tt> command:</p>
<blockquote>
<tt class="docutils literal">pyinstaller</tt> <em>options</em> <em>name</em><tt class="docutils literal">.spec</tt></blockquote>
<p>When you create a spec file, most command options are encoded in the spec file.
When you build from a spec file, those options cannot be changed.
If they are given on the command line they are ignored and
replaced by the options in the spec file.</p>
<p>Only the following command-line options have an effect when building from a spec file:</p>
<ul class="simple">
<li>--upx-dir=</li>
<li>--distpath=</li>
<li>--workpath=</li>
<li>--noconfirm</li>
<li>--ascii</li>
</ul>
<div class="section" id="spec-file-operation">
<h2><a class="toc-backref" href="#id51">Spec File Operation</a></h2>
<p>After <cite>PyInstaller</cite> creates a spec file,
or opens a spec file when one is given instead of a script,
the <tt class="docutils literal">pyinstaller</tt> command executes the spec file as code.
Your bundled application is created by the execution of the spec file.
The following is an shortened example of a spec file for a minimal, one-folder app:</p>
<pre class="literal-block">
block_cipher = None
a = Analysis(['minimal.py'],
     pathex=['/Developer/PItests/minimal'],
     binaries=None,
     datas=None,
     hiddenimports=[],
     hookspath=None,
     runtime_hooks=None,
     excludes=None,
     cipher=block_cipher)
pyz = PYZ(a.pure, a.zipped_data,
     cipher=block_cipher)
exe = EXE(pyz,... )
coll = COLLECT(...)
</pre>
<p>The statements in a spec file create instances of four classes,
<tt class="docutils literal">Analysis</tt>, <tt class="docutils literal">PYZ</tt>, <tt class="docutils literal">EXE</tt> and <tt class="docutils literal">COLLECT</tt>.</p>
<ul class="simple">
<li>A new instance of class <tt class="docutils literal">Analysis</tt> takes a list of script names as input.
It analyzes all imports and other dependencies.
The resulting object (assigned to <tt class="docutils literal">a</tt>) contains lists of dependencies
in class members named:<ul>
<li><tt class="docutils literal">scripts</tt>: the python scripts named on the command line;</li>
<li><tt class="docutils literal">pure</tt>: pure python modules needed by the scripts;</li>
<li><tt class="docutils literal">binaries</tt>: non-python modules needed by the scripts;</li>
<li><tt class="docutils literal">datas</tt>: non-binary files included in the app.</li>
</ul>
</li>
<li>An instance of class <tt class="docutils literal">PYZ</tt> is a <tt class="docutils literal">.pyz</tt> archive (described
under <a class="reference internal" href="#inspecting-archives">Inspecting Archives</a> below), which contains all the
Python modules from <tt class="docutils literal">a.pure</tt>.</li>
<li>An instance of <tt class="docutils literal">EXE</tt> is built from the analyzed scripts and the <tt class="docutils literal">PYZ</tt>
archive. This object creates the executable file.</li>
<li>An instance of <tt class="docutils literal">COLLECT</tt> creates the output folder from all the other parts.</li>
</ul>
<p>In one-file mode, there is no call to <tt class="docutils literal">COLLECT</tt>, and the
<tt class="docutils literal">EXE</tt> instance receives all of the scripts, modules and binaries.</p>
<p>You modify the spec file to pass additional values to <tt class="docutils literal">Analysis</tt> and
to <tt class="docutils literal">EXE</tt>.</p>
</div>
<div class="section" id="adding-files-to-the-bundle">
<h2><a class="toc-backref" href="#id52">Adding Files to the Bundle</a></h2>
<p>To add files to the bundle, you create a list that describes the files
and supply it to the <tt class="docutils literal">Analysis</tt> call.
To find the data files at run-time, see <a class="reference internal" href="#run-time-information">Run-time Information</a>.</p>
<div class="section" id="adding-data-files">
<h3><a class="toc-backref" href="#id53">Adding Data Files</a></h3>
<p>To have data files included in the bundle, provide a list that
describes the files as the value of the <tt class="docutils literal">datas=</tt> argument to <tt class="docutils literal">Analysis</tt>.
The list of data files is a list of tuples.
Each tuple has two values, both of which must be strings:</p>
<blockquote>
<ul class="simple">
<li>The first string specifies the file or files as they are in this system now.</li>
<li>The second specifies the name of the folder to contain
the files at run-time.</li>
</ul>
</blockquote>
<p>For example, to add a single README file to the top level of a one-folder app,
you could modify the spec file as follows:</p>
<pre class="literal-block">
a = Analysis(...
     datas=[ ('src/README.txt', '.') ],
     ...
     )
</pre>
<p>You have made the <tt class="docutils literal">datas=</tt> argument a one-item list.
The item is a tuple in which the first string says the existing file
is <tt class="docutils literal">src/README.txt</tt>.
That file will be looked up (relative to the location of the spec file)
and copied into the top level of the bundled app.</p>
<p>The strings may use either <tt class="docutils literal">/</tt> or <tt class="docutils literal">\</tt> as the path separator character.
You can specify input files using &quot;glob&quot; abbreviations.
For example to include all the <tt class="docutils literal">.mp3</tt> files from a certain folder:</p>
<pre class="literal-block">
a = Analysis(...
     datas= [ ('/mygame/sfx/*.mp3', 'sfx' ) ],
     ...
     )
</pre>
<p>All the <tt class="docutils literal">.mp3</tt> files in the folder <tt class="docutils literal">/mygame/sfx</tt> will be copied
into a folder named <tt class="docutils literal">sfx</tt> in the bundled app.</p>
<p>The spec file is more readable if you create the list of added files
in a separate statement:</p>
<pre class="literal-block">
added_files = [
         ( '/mygame/sfx/*.mp3', 'sfx' ),
         ( 'src/README.txt', '.' )
         ]
    a = Analysis(...
         datas = added_files,
         ...
         )
</pre>
<p>You can also include the entire contents of a folder:</p>
<pre class="literal-block">
added_files = [
         ( '/mygame/data', 'data' ),
         ( '/mygame/sfx/*.mp3', 'sfx' ),
         ( 'src/README.txt', '.' )
         ]
</pre>
<p>The folder <tt class="docutils literal">/mygame/data</tt> will be reproduced under the name
<tt class="docutils literal">data</tt> in the bundle.</p>
</div>
<div class="section" id="using-data-files-from-a-module">
<h3><a class="toc-backref" href="#id54">Using Data Files from a Module</a></h3>
<p>If the data files you are adding are contained within a Python module,
you can retrieve them using <tt class="docutils literal">pkgutils.get_data()</tt>.</p>
<p>For example, suppose that part of your application is a module named <tt class="docutils literal">helpmod</tt>.
In the same folder as your script and its spec file you have this folder
arrangement:</p>
<pre class="literal-block">
helpmod
        __init__.py
        helpmod.py
        help_data.txt
</pre>
<p>Because your script includes the statement <tt class="docutils literal">import helpmod</tt>,
<cite>PyInstaller</cite> will create this folder arrangement in your bundled app.
However, it will only include the <tt class="docutils literal">.py</tt> files.
The data file <tt class="docutils literal">help_data.txt</tt> will not be automatically included.
To cause it to be included also, you would add a <tt class="docutils literal">datas</tt> tuple
to the spec file:</p>
<pre class="literal-block">
a = Analysis(...
     datas= [ ('helpmod/help_data.txt', 'helpmod' ) ],
     ...
     )
</pre>
<p>When your script executes, you could find <tt class="docutils literal">help_data.txt</tt> by
using its base folder path, as described in the previous section.
However, this data file is part of a module, so you can also retrieve
its contents using the standard library function <tt class="docutils literal">pkgutil.get_data()</tt>:</p>
<pre class="literal-block">
import pkgutil
help_bin = pkgutil.get_data( 'helpmod', 'help_data.txt' )
</pre>
<p>In Python 3, this returns the contents of the <tt class="docutils literal">help_data.txt</tt> file as a binary string.
If it is actually characters, you must decode it:</p>
<pre class="literal-block">
help_utf = help_bin.decode('UTF-8', 'ignore')
</pre>
</div>
<div class="section" id="adding-binary-files">
<h3><a class="toc-backref" href="#id55">Adding Binary Files</a></h3>
<p>To add binary files, make a list of tuples that describe the files needed.
Assign the list of tuples to the <tt class="docutils literal">binaries=</tt> argument of Analysis.</p>
<p>Normally <cite>PyInstaller</cite> learns about <tt class="docutils literal">.so</tt> and <tt class="docutils literal">.dll</tt> libraries by
analyzing the imported modules.
Sometimes it is not clear that a module is imported;
in that case you use a <tt class="docutils literal"><span class="pre">--hidden-import=</span></tt> command option.
But even that might not find all dependencies.</p>
<p>Suppose you have a module <tt class="docutils literal">special_ops.so</tt> that is written in C
and uses the Python C-API.
Your program imports <tt class="docutils literal">special_ops</tt>, and <cite>PyInstaller</cite> finds and
includes <tt class="docutils literal">special_ops.so</tt>.
But perhaps <tt class="docutils literal">special_ops.so</tt> links to <tt class="docutils literal">libiodbc.2.dylib</tt>.
<cite>PyInstaller</cite> does not find this dependency.
You could add it to the bundle this way:</p>
<pre class="literal-block">
a = Analysis(...
         binaries=[ ( '/usr/lib/libiodbc.2.dylib', 'libiodbc.dylib' ) ],
         ...
</pre>
<p>As with data files, if you have multiple binary files to add,
create the list in a separate statement and pass the list by name.</p>
</div>
<div class="section" id="advanced-methods-of-adding-files">
<h3><a class="toc-backref" href="#id56">Advanced Methods of Adding Files</a></h3>
<p><cite>PyInstaller</cite> supports a more advanced (and complex) way of adding
files to the bundle that may be useful for special cases.
See <a class="reference internal" href="#the-toc-and-tree-classes">The TOC and Tree Classes</a> below.</p>
</div>
</div>
<div class="section" id="giving-run-time-python-options">
<h2><a class="toc-backref" href="#id57">Giving Run-time Python Options</a></h2>
<p>You can pass command-line options to the Python interpreter.
The interpreter takes a number of command-line options but only the
following are supported for a bundled app:</p>
<ul class="simple">
<li><tt class="docutils literal">v</tt> to write a message to stdout each time a module is initialized.</li>
<li><tt class="docutils literal">u</tt> for unbuffered stdio.</li>
<li><tt class="docutils literal">W</tt> and an option to change warning behavior: <tt class="docutils literal">W ignore</tt> or
<tt class="docutils literal">W once</tt> or <tt class="docutils literal">W error</tt>.</li>
</ul>
<p>To pass one or more of these options,
create a list of tuples, one for each option, and pass the list as
an additional argument to the EXE call.
Each tuple has three elements:</p>
<ul class="simple">
<li>The option as a string, for example <tt class="docutils literal">v</tt> or <tt class="docutils literal">W ignore</tt>.</li>
<li>None</li>
<li>The string <tt class="docutils literal">OPTION</tt></li>
</ul>
<p>For example modify the spec file this way:</p>
<pre class="literal-block">
options = [ ('v', None, 'OPTION'), ('W ignore', None, 'OPTION') ]
a = Analysis( ...
            )
...
exe = EXE(pyz,
      a.scripts,
      options,   &lt;--- added line
      exclude_binaries=...
      )
</pre>
</div>
<div class="section" id="spec-file-options-for-a-mac-os-x-bundle">
<h2><a class="toc-backref" href="#id58">Spec File Options for a Mac&nbsp;OS&nbsp;X Bundle</a></h2>
<p>When you build a windowed Mac&nbsp;OS&nbsp;X app
(that is, running in Mac&nbsp;OS&nbsp;X, you specify the <tt class="docutils literal"><span class="pre">--onefile</span> <span class="pre">--windowed</span></tt> options),
the spec file contains an additional statement to
create the Mac&nbsp;OS&nbsp;X application bundle, or app folder:</p>
<pre class="literal-block">
app = BUNDLE(exe,
         name='myscript.app',
         icon=None,
         bundle_identifier=None)
</pre>
<p>The <tt class="docutils literal">icon=</tt> argument to <tt class="docutils literal">BUNDLE</tt> will have the path to an icon file
that you specify using the <tt class="docutils literal"><span class="pre">--icon=</span></tt> option.
The <tt class="docutils literal">bundle_identifier</tt> will have the value you specify with the
<tt class="docutils literal"><span class="pre">--osx-bundle-identifier=</span></tt> option.</p>
<p>An <tt class="docutils literal">Info.plist</tt> file is an important part of a Mac&nbsp;OS&nbsp;X app bundle.
(See the <a class="reference external" href="https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html">Apple bundle overview</a> for a discussion of the contents
of <tt class="docutils literal">Info.plist</tt>.)</p>
<p><cite>PyInstaller</cite> creates a minimal <tt class="docutils literal">Info.plist</tt>.
You can add or overwrite entries in the plist by passing an
<tt class="docutils literal">info_plist=</tt> parameter to the BUNDLE call.
The value of this argument is a Python dict.
Each key and value in the dict becomes a key and value in the <tt class="docutils literal">Info.plist</tt> file.
For example, when you use PyQt5,
you can set <tt class="docutils literal">NSHighResolutionCapable</tt> to <tt class="docutils literal">True</tt> to let your app
also work in retina screen:</p>
<pre class="literal-block">
app = BUNDLE(exe,
         name='myscript.app',
         icon=None,
         bundle_identifier=None
         info_plist={
            'NSHighResolutionCapable': 'True'
            },
         )
</pre>
<p>The <tt class="docutils literal">info_plist=</tt> parameter only handles simple key:value pairs.
It cannot handle nested XML arrays.
For example, if you want to modify <tt class="docutils literal">Info.plist</tt> to tell Mac&nbsp;OS&nbsp;X
what filetypes your app supports, you must add a
<tt class="docutils literal">CFBundleDocumentTypes</tt> entry to <tt class="docutils literal">Info.plist</tt>
(see <a class="reference external" href="https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-101685">Apple document types</a>).
The value of that keyword is a list of dicts,
each containing up to five key:value pairs.</p>
<p>To add such a value to your app's <tt class="docutils literal">Info.plist</tt> you must edit the
plist file separately after <cite>PyInstaller</cite> has created the app.
However, when you re-run <cite>PyInstaller</cite>, your changes will be wiped out.
One solution is to prepare a complete <tt class="docutils literal">Info.plist</tt> file and
copy it into the app after creating it.</p>
<p>Begin by building and testing the windowed app.
When it works, copy the <tt class="docutils literal">Info.plist</tt> prepared by <cite>PyInstaller</cite>.
This includes the <tt class="docutils literal">CFBundleExecutable</tt> value as well as the
icon path and bundle identifier if you supplied them.
Edit the <tt class="docutils literal">Info.plist</tt> as necessary to add more items
and save it separately.</p>
<p>From that point on, to rebuild the app call <cite>PyInstaller</cite> in a shell script,
and follow it with a statement such as:</p>
<pre class="literal-block">
cp -f Info.plist dist/myscript.app/Contents/Info.plist
</pre>
</div>
<div class="section" id="multipackage-bundles">
<h2><a class="toc-backref" href="#id59">Multipackage Bundles</a></h2>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This feature is broken in the <cite>PyInstaller</cite> 3.0 release.
Do not attempt building multipackage bundles until the feature
is fixed. If this feature is important to you,
follow  and comment on <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/issues/1527">PyInstaller Issue #1527</a>.</p>
</div>
<p>Some products are made of several different apps,
each of which might
depend on a common set of third-party libraries, or share code in other ways.
When packaging such an product it
would be a pity to treat each app in isolation, bundling it with
all its dependencies, because that means storing duplicate copies
of code and libraries.</p>
<p>You can use the multipackage feature to bundle a set of executable apps
so that they share single copies of libraries.
You can do this with either one-file or one-folder apps.
Each dependency (a DLL, for example) is packaged only once, in one of the apps.
Any other apps in the set that depend on that DLL
have an &quot;external reference&quot; to it, telling them
to extract that dependency from the executable file of the app that contains it.</p>
<p>This saves disk space because each dependency is stored only once.
However, to follow an external reference takes extra time when an app is starting up.
All but one of the apps in the set will have slightly slower launch times.</p>
<p>The external references between binaries include hard-coded
paths to the output directory, and cannot be rearranged.
If you use one-folder mode, you must
install all the application folders within a single parent directory.
If you use one-file mode, you must place all
the related applications in the same directory
when you install the application.</p>
<p>To build such a set of apps you must code a custom
spec file that contains  a call to the <tt class="docutils literal">MERGE</tt> function.
This function takes a list of analyzed scripts,
finds their common dependencies, and modifies the analyses
to minimize the storage cost.</p>
<p>The order of the analysis objects in the argument list matters.
The MERGE function packages each dependency into the
first script from left to right that needs that dependency.
A script that comes later in the list and needs the same file
will have an external reference to the prior script in the list.
You might sequence the scripts to place the most-used scripts first in the list.</p>
<p>A custom spec file for a multipackage bundle contains one call to the MERGE function:</p>
<pre class="literal-block">
MERGE(*args)
</pre>
<p>MERGE is used after the analysis phase and before <tt class="docutils literal">EXE</tt> and <tt class="docutils literal">COLLECT</tt>.
Its variable-length list of arguments consists of
a list of tuples, each tuple having three elements:</p>
<ul class="simple">
<li>The first element is an Analysis object, an instance of class Analysis,
as applied to one of the apps.</li>
<li>The second element is the script name of the analyzed app (without the <tt class="docutils literal">.py</tt> extension).</li>
<li>The third element is the name for the executable (usually the same as the script).</li>
</ul>
<p>MERGE examines the Analysis objects to learn the dependencies of each script.
It modifies these objects to avoid duplication of libraries and modules.
As a result the packages generated will be connected.</p>
<div class="section" id="example-merge-spec-file">
<h3><a class="toc-backref" href="#id60">Example MERGE spec file</a></h3>
<p>One way to construct a spec file for a multipackage bundle is to
first build a spec file for each app in the package.
Suppose you have a product that comprises three apps named
(because we have no imagination) <tt class="docutils literal">foo</tt>, <tt class="docutils literal">bar</tt> and <tt class="docutils literal">zap</tt>:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">pyi-makespec</span></tt> <em>options as appropriate...</em> <tt class="docutils literal">foo.py</tt></p>
<p><tt class="docutils literal"><span class="pre">pyi-makespec</span></tt> <em>options as appropriate...</em> <tt class="docutils literal">bar.py</tt></p>
<p><tt class="docutils literal"><span class="pre">pyi-makespec</span></tt> <em>options as appropriate...</em> <tt class="docutils literal">zap.py</tt></p>
</blockquote>
<p>Check for warnings and test each of the apps individually.
Deal with any hidden imports and other problems.
When all three work correctly,
combine the statements from the three files <tt class="docutils literal">foo.spec</tt>, <tt class="docutils literal">bar.spec</tt> and <tt class="docutils literal">zap.spec</tt>
as follows.</p>
<p>First copy the Analysis statements from each,
changing them to give each Analysis object a unique name:</p>
<pre class="literal-block">
foo_a = Analysis(['foo.py'],
        pathex=['/the/path/to/foo'],
        hiddenimports=[],
        hookspath=None)

bar_a = Analysis(['bar.py'], etc., etc...

zap_a = Analysis(['zap.py'], etc., etc...
</pre>
<p>Now call the MERGE method to process the three Analysis objects:</p>
<pre class="literal-block">
MERGE( (foo_a, 'foo', 'foo'), (bar_a, 'bar', 'bar'), (zap_a, 'zap', 'zap') )
</pre>
<p>The Analysis objects <tt class="docutils literal">foo_a</tt>, <tt class="docutils literal">bar_a</tt>, and <tt class="docutils literal">zap_a</tt> are modified
so that the latter two refer to the first for common dependencies.</p>
<p>Following this you can copy the <tt class="docutils literal">PYZ</tt>, <tt class="docutils literal">EXE</tt> and <tt class="docutils literal">COLLECT</tt> statements from
the original three spec files,
substituting the unique names of the Analysis objects
where the original spec files have <tt class="docutils literal">a.</tt>, for example:</p>
<pre class="literal-block">
foo_pyz = PYZ(foo_a.pure)
foo_exe = EXE(foo_pyz, foo_a.scripts, ... etc.
foo_coll = COLLECT( foo_exe, foo_a.binaries, foo_a.datas... etc.

bar_pyz = PYZ(bar_a.pure)
bar_exe = EXE(bar_pyz, bar_a.scripts, ... etc.
bar_coll = COLLECT( bar_exe, bar_a.binaries, bar_a.datas... etc.
</pre>
<p>(If you are building one-file apps, there is no <tt class="docutils literal">COLLECT</tt> step.)
Save the combined spec file as <tt class="docutils literal">foobarzap.spec</tt> and then build it:</p>
<pre class="literal-block">
pyi-build foobarzap.spec
</pre>
<p>The output in the <tt class="docutils literal">dist</tt> folder will be all three apps, but
the apps <tt class="docutils literal">dist/bar/bar</tt> and <tt class="docutils literal">dist/zap/zap</tt> will refer to
the contents of <tt class="docutils literal">dist/foo/</tt> for shared dependencies.</p>
<p>There are several multipackage examples in the
<cite>PyInstaller</cite> distribution folder under <tt class="docutils literal">/tests/old_suite/multipackage</tt>.</p>
<p>Remember that a spec file is executable Python.
You can use all the Python facilities (<tt class="docutils literal">for</tt> and <tt class="docutils literal">with</tt>
and the members of <tt class="docutils literal">sys</tt> and <tt class="docutils literal">io</tt>)
in creating the Analysis
objects and performing the <tt class="docutils literal">PYZ</tt>, <tt class="docutils literal">EXE</tt> and <tt class="docutils literal">COLLECT</tt> statements.
You may also need to know and use <a class="reference internal" href="#the-toc-and-tree-classes">The TOC and Tree Classes</a> described below.</p>
</div>
</div>
<div class="section" id="globals-available-to-the-spec-file">
<h2><a class="toc-backref" href="#id61">Globals Available to the Spec File</a></h2>
<p>While a spec file is executing it has access to a limited set of global names.
These names include the classes defined by <cite>PyInstaller</cite>:
<tt class="docutils literal">Analysis</tt>, <tt class="docutils literal">BUNDLE</tt>, <tt class="docutils literal">COLLECT</tt>, <tt class="docutils literal">EXE</tt>, <tt class="docutils literal">MERGE</tt>,
<tt class="docutils literal">PYZ</tt>, <tt class="docutils literal">TOC</tt> and <tt class="docutils literal">Tree</tt>,
which are discussed in the preceding sections.</p>
<p>Other globals contain information about the build environment:</p>
<dl class="docutils">
<dt><tt class="docutils literal">DISTPATH</tt></dt>
<dd>The relative path to the <tt class="docutils literal">dist</tt> folder where
the application will be stored.
The default path is relative to the current directory.
If the <tt class="docutils literal"><span class="pre">--distpath=</span></tt> option is used, <tt class="docutils literal">DISTPATH</tt> contains that value.</dd>
<dt><tt class="docutils literal">HOMEPATH</tt></dt>
<dd>The absolute path to the <cite>PyInstaller</cite>
distribution, typically in the current Python site-packages folder.</dd>
<dt><tt class="docutils literal">SPEC</tt></dt>
<dd>The complete spec file argument given to the
<tt class="docutils literal">pyinstaller</tt> command, for example <tt class="docutils literal">myscript.spec</tt>
or <tt class="docutils literal">source/myscript.spec</tt>.</dd>
<dt><tt class="docutils literal">SPECPATH</tt></dt>
<dd>The path prefix to the <tt class="docutils literal">SPEC</tt> value as returned by <tt class="docutils literal">os.split()</tt>.</dd>
<dt><tt class="docutils literal">specnm</tt></dt>
<dd>The name of the spec file, for example <tt class="docutils literal">myscript</tt>.</dd>
<dt><tt class="docutils literal">workpath</tt></dt>
<dd>The path to the <tt class="docutils literal">build</tt> directory. The default is relative to
the current directory. If the <tt class="docutils literal">workpath=</tt> option is used,
<tt class="docutils literal">workpath</tt> contains that value.</dd>
<dt><tt class="docutils literal">WARNFILE</tt></dt>
<dd>The full path to the warnings file in the build directory,
for example <tt class="docutils literal">build/warnmyscript.txt</tt>.</dd>
</dl>
</div>
</div>
<div class="section" id="when-things-go-wrong">
<h1><a class="toc-backref" href="#id62">When Things Go Wrong</a></h1>
<p>The information above covers most normal uses of <cite>PyInstaller</cite>.
However, the variations of Python and third-party libraries are
endless and unpredictable.
It may happen that when you attempt to bundle your app either
<cite>PyInstaller</cite> itself, or your bundled app, terminates with a Python traceback.
Then please consider the following actions in sequence, before
asking for technical help.</p>
<div class="section" id="recipes-and-examples-for-specific-problems">
<h2><a class="toc-backref" href="#id63">Recipes and Examples for Specific Problems</a></h2>
<p>The <cite>PyInstaller</cite> <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/FAQ">FAQ</a> page has work-arounds for some common problems.
Code examples for some advanced uses and some common
problems are available on our <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/Recipes">PyInstaller Recipes</a> page.
Some of the recipes there include:</p>
<ul class="simple">
<li>A more sophisticated way of collecting data files
than the one shown above (<a class="reference internal" href="#adding-files-to-the-bundle">Adding Files to the Bundle</a>).</li>
<li>Bundling a typical Django app.</li>
<li>A use of a run-time hook to set the PyQt4 API level.</li>
<li>A workaround for a multiprocessing constraint under Windows.</li>
</ul>
<p>and others.
Many of these Recipes were contributed by users.
Please feel free to contribute more recipes!</p>
</div>
<div class="section" id="finding-out-what-went-wrong">
<h2><a class="toc-backref" href="#id64">Finding out What Went Wrong</a></h2>
<div class="section" id="build-time-messages">
<h3><a class="toc-backref" href="#id65">Build-time Messages</a></h3>
<p>When the <tt class="docutils literal">Analysis</tt> step runs, it produces error and warning messages.
These display after the command line if the <tt class="docutils literal"><span class="pre">--log-level</span></tt> option allows it.
Analysis also puts messages in a warnings file
named <tt class="docutils literal">build/</tt><em>name</em><tt class="docutils literal">/warn</tt><em>name</em><tt class="docutils literal">.txt</tt> in the
<tt class="docutils literal"><span class="pre">work-path=</span></tt> directory.</p>
<p>Analysis creates a message when it detects an import
and the module it names cannot be found.
A message may also be produced when a class or function is declared in
a package (an <tt class="docutils literal">__init__.py</tt> module), and the import specifies
<tt class="docutils literal">package.name</tt>. In this case, the analysis can't tell if name is supposed to
refer to a submodule or package.</p>
<p>The &quot;module not found&quot; messages are not classed as errors because
typically there are many of them.
For example, many standard modules
conditionally import modules for different platforms that may or may
not be present.</p>
<p>All &quot;module not found&quot; messages are written to the
<tt class="docutils literal">build/</tt><em>name</em><tt class="docutils literal">/warn</tt><em>name</em><tt class="docutils literal">.txt</tt> file.
They are not displayed to standard output because there are many of them.
Examine the warning file; often there will be dozens of modules not found,
but their absence has no effect.</p>
<p>When you run the bundled app and it terminates with an ImportError,
that is the time to examine the warning file.
Then see <a class="reference internal" href="#helping-pyinstaller-find-modules">Helping PyInstaller Find Modules</a> below for how to proceed.</p>
</div>
<div class="section" id="build-time-dependency-graph">
<h3><a class="toc-backref" href="#id66">Build-Time Dependency Graph</a></h3>
<p>If you specify <tt class="docutils literal"><span class="pre">--log-level=DEBUG</span></tt> to the <tt class="docutils literal">pyinstaller</tt> command,
<cite>PyInstaller</cite> writes two files of data about dependencies into the
build folder.</p>
<p>The file <tt class="docutils literal">build/</tt><em>name</em><tt class="docutils literal">/xref-</tt><em>name</em><tt class="docutils literal">.html</tt> in the
<tt class="docutils literal"><span class="pre">work-path=</span></tt> directory is an HTML file that lists the full
contents of the import graph, showing which modules are imported
by which.
You can open it in any web browser.
Find a module name, then keep clicking the &quot;imported by&quot; links
until you find the top-level import that causes that module to be included.</p>
<p>The file <tt class="docutils literal">build/</tt><em>name</em><tt class="docutils literal">/graph-</tt><em>name</em><tt class="docutils literal">.dot</tt> in the
<tt class="docutils literal"><span class="pre">work-path=</span></tt> directory is a <a class="reference external" href="http://graphviz.org/Home.php">GraphViz</a> input file.
You can process it with the <a class="reference external" href="http://graphviz.org/Home.php">GraphViz</a> command <tt class="docutils literal">dot</tt> to produce
a graphical display of the import dependencies.</p>
<p>These files are very large because even the simplest &quot;hello world&quot;
Python program ends up including a large number of standard modules.
For this reason the graph file is not very useful in this release.</p>
</div>
<div class="section" id="build-time-python-errors">
<h3><a class="toc-backref" href="#id67">Build-Time Python Errors</a></h3>
<p><cite>PyInstaller</cite> sometimes terminates by raising a Python exception.
In most cases the reason is clear from the exception message,
for example &quot;Your system is not supported&quot;, or &quot;Pyinstaller
requires at least Python 2.7&quot;.
Others clearly indicate a bug that should be reported.</p>
<p>One of these errors can be puzzling, however:
<tt class="docutils literal"><span class="pre">IOError(&quot;Python</span> library not <span class="pre">found!&quot;)</span></tt>
<cite>PyInstaller</cite> needs to bundle the Python library, which is the
main part of the Python interpreter, linked as a dynamic load library.
The name and location of this file varies depending on the platform in use.
Some Python installations do not include a dynamic Python library
by default (a static-linked one may be present but cannot be used).
You may need to install a development package of some kind.
Or, the library may exist but is not in a folder where <cite>PyInstaller</cite>
is searching.</p>
<p>The places where <cite>PyInstaller</cite> looks for the python library are
different in different operating systems, but <tt class="docutils literal">/lib</tt> and <tt class="docutils literal">/usr/lib</tt>
are checked in most systems.
If you cannot put the python library there,
try setting the correct path in the environment variable
<tt class="docutils literal">LD_LIBRARY_PATH</tt> in Linux or
<tt class="docutils literal">DYLD_LIBRARY_PATH</tt> in OS X.</p>
</div>
<div class="section" id="getting-debug-messages">
<h3><a class="toc-backref" href="#id68">Getting Debug Messages</a></h3>
<p>Giving the <tt class="docutils literal"><span class="pre">--debug</span></tt> option causes the bundled executable itself to
write progress messages when it runs.
This can be useful during development of a complex package,
or when your app doesn't seem to be starting,
or just to learn how the runtime works.</p>
<p>Normally the debug progress messages go to standard output.
If the <tt class="docutils literal"><span class="pre">--windowed</span></tt> option is used when bundling a Windows app,
they are displayed as MessageBoxes.
For a <tt class="docutils literal"><span class="pre">--windowed</span></tt> Mac OS app they are not displayed.</p>
<p>Remember to bundle without <tt class="docutils literal"><span class="pre">--debug</span></tt> for your production version.
Users would find the messages annoying.</p>
</div>
<div class="section" id="getting-python-s-verbose-imports">
<h3><a class="toc-backref" href="#id69">Getting Python's Verbose Imports</a></h3>
<p>You can also pass a <tt class="docutils literal"><span class="pre">-v</span></tt> (verbose imports) flag to the embedded Python interpreter
(see <a class="reference internal" href="#giving-run-time-python-options">Giving Run-time Python Options</a> above).
This can be extremely useful.
It can be informative even with apps that are apparently working,
to make sure that they are getting all imports from the bundle,
and not leaking out to the local installed Python.</p>
<p>Python verbose and warning messages always go to standard output
and are not visible when the <tt class="docutils literal"><span class="pre">--windowed</span></tt> option is used.
Remember to not use this in the distributed program.</p>
</div>
</div>
<div class="section" id="helping-pyinstaller-find-modules">
<h2><a class="toc-backref" href="#id70">Helping PyInstaller Find Modules</a></h2>
<div class="section" id="extending-the-path">
<h3><a class="toc-backref" href="#id71">Extending the Path</a></h3>
<p>If Analysis recognizes that a module is needed, but cannot find that module,
it is often because the script is manipulating <tt class="docutils literal">sys.path</tt>.
The easiest thing to do in this case is to use the <tt class="docutils literal"><span class="pre">--paths=</span></tt> option
to list all the other places that the script might be searching for imports:</p>
<pre class="literal-block">
pyi-makespec --paths=/path/to/thisdir \
             --paths=/path/to/otherdir myscript.py
</pre>
<p>These paths will be noted in the spec file.
They will be added to the current <tt class="docutils literal">sys.path</tt> during analysis.</p>
</div>
<div class="section" id="listing-hidden-imports">
<h3><a class="toc-backref" href="#id72">Listing Hidden Imports</a></h3>
<p>If Analysis thinks it has found all the imports,
but the app fails with an import error,
the problem is a hidden import; that is, an import that is not
visible to the analysis phase.</p>
<p>Hidden imports can occur when the code is using <tt class="docutils literal">__import__</tt>
or perhaps <tt class="docutils literal">exec</tt> or <tt class="docutils literal">eval</tt>.
Hidden imports can also occur when an extension module uses the
Python/C API to do an import.
When this occurs, Analysis can detect nothing.
There will be no warnings, only an ImportError at run-time.</p>
<p>To find these hidden imports,
build the app with the <tt class="docutils literal"><span class="pre">-v</span></tt> flag (<a class="reference internal" href="#getting-python-s-verbose-imports">Getting Python's Verbose Imports</a> above)
and run it.</p>
<p>Once you know what modules are needed, you add the needed modules
to the bundle using the <tt class="docutils literal"><span class="pre">--hidden-import=</span></tt> command option,
or by editing the spec file,
or with a hook file (see <a class="reference internal" href="#understanding-pyinstaller-hooks">Understanding PyInstaller Hooks</a> below).</p>
</div>
<div class="section" id="extending-a-package-s-path">
<h3><a class="toc-backref" href="#id73">Extending a Package's <tt class="docutils literal">__path__</tt></a></h3>
<p>Python allows a script to extend the search path used for imports
through the <tt class="docutils literal">__path__</tt> mechanism.
Normally, the <tt class="docutils literal">__path__</tt> of an imported module has only one entry,
the directory in which the <tt class="docutils literal">__init__.py</tt> was found.
But <tt class="docutils literal">__init__.py</tt> is free to extend its <tt class="docutils literal">__path__</tt> to include other directories.
For example, the <tt class="docutils literal">win32com.shell.shell</tt> module actually resolves to
<tt class="docutils literal">win32com/win32comext/shell/shell.pyd</tt>.
This is because <tt class="docutils literal">win32com/__init__.py</tt> appends <tt class="docutils literal"><span class="pre">../win32comext</span></tt> to its <tt class="docutils literal">__path__</tt>.</p>
<p>Because the <tt class="docutils literal">__init__.py</tt> of an imported module
is not actually executed during analysis,
changes it makes to <tt class="docutils literal">__path__</tt> are not seen by <cite>PyInstaller</cite>.
We fix the problem with the same hook mechanism we use for hidden imports,
with some additional logic; see <a class="reference internal" href="#understanding-pyinstaller-hooks">Understanding PyInstaller Hooks</a> below.</p>
<p>Note that manipulations of <tt class="docutils literal">__path__</tt> hooked in this way apply only
to the Analysis.
At runtime all imports are intercepted and satisfied from within the
bundle. <tt class="docutils literal">win32com.shell</tt> is resolved the same
way as <tt class="docutils literal">win32com.anythingelse</tt>, and <tt class="docutils literal">win32com.__path__</tt>
knows nothing of <tt class="docutils literal"><span class="pre">../win32comext</span></tt>.</p>
<p>Once in a while, that's not enough.</p>
</div>
<div class="section" id="changing-runtime-behavior">
<h3><a class="toc-backref" href="#id74">Changing Runtime Behavior</a></h3>
<p>More bizarre situations can be accomodated with runtime hooks.
These are small scripts that manipulate the environment before your main script runs,
effectively providing additional top-level code to your script.</p>
<p>There are two ways of providing runtime hooks.
You can name them with the option <tt class="docutils literal"><span class="pre">--runtime-hook=</span></tt><em>path-to-script</em>.</p>
<p>Second, some runtime hooks are provided.
At the end of an analysis,
the names in the module list produced by the Analysis phase are looked up in
<tt class="docutils literal">loader/rthooks.dat</tt> in the <cite>PyInstaller</cite> install folder.
This text file is the string representation of a
Python dictionary. The key is the module name, and the value is a list
of hook-script pathnames.
If there is a match, those scripts are included in the bundled app
and will be called before your main script starts.</p>
<p>Hooks you name with the option are executed
in the order given, and before any installed runtime hooks.
If you specify  <tt class="docutils literal"><span class="pre">--runtime-hook=file1.py</span> <span class="pre">--runtime-hook=file2.py</span></tt>
then the execution order at runtime will be:</p>
<ol class="arabic simple">
<li>Code of <tt class="docutils literal">file1.py</tt>.</li>
<li>Code of <tt class="docutils literal">file2.py</tt>.</li>
<li>Any hook specified for an included module that is found
in <tt class="docutils literal">rthooks/rthooks.dat</tt>.</li>
<li>Your main script.</li>
</ol>
<p>Hooks called in this way, while they need to be careful of what they import,
are free to do almost anything.
One reason to write a run-time hook is to
override some functions or variables from some modules.
A good example of this is the Django runtime
hook (see <tt class="docutils literal">loader/rthooks/pyi_rth_django.py</tt> in the
<cite>PyInstaller</cite> folder).
Django imports some modules dynamically and it is looking
for some <tt class="docutils literal">.py</tt> files.
However <tt class="docutils literal">.py</tt> files are not available in the one-file bundle.
We need to override the function
<tt class="docutils literal">django.core.management.find_commands</tt>
in a way that will just return a list of values.
The runtime hook does this as follows:</p>
<pre class="literal-block">
import django.core.management
def _find_commands(_):
    return &quot;&quot;&quot;cleanup shell runfcgi runserver&quot;&quot;&quot;.split()
django.core.management.find_commands = _find_commands
</pre>
</div>
</div>
<div class="section" id="getting-the-latest-version">
<h2><a class="toc-backref" href="#id75">Getting the Latest Version</a></h2>
<p>If you have some reason to think you have found a bug in <cite>PyInstaller</cite>
you can try downloading the latest development version.
This version might have fixes or features that are not yet at <a class="reference external" href="https://pypi.python.org/pypi/PyInstaller/">PyPI</a>.
You can download the latest stable version and the latest development
version from the <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/releases">PyInstaller Downloads</a> page.</p>
<p>You can also install the latest version of <cite>PyInstaller</cite> directly
using <a class="reference external" href="http://www.pip-installer.org/">pip</a>:</p>
<pre class="literal-block">
pip install -e https://github.com/pyinstaller/pyinstaller/archive/develop.zip
</pre>
</div>
<div class="section" id="asking-for-help">
<h2><a class="toc-backref" href="#id76">Asking for Help</a></h2>
<p>When none of the above suggestions help,
do ask for assistance on the <a class="reference external" href="https://groups.google.com/forum/#!forum/pyinstaller">PyInstaller Email List</a>.</p>
<p>Then, if you think it likely that you see a bug in <cite>PyInstaller</cite>,
refer to the <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/How-to-Report-Bugs">How to Report Bugs</a> page.</p>
</div>
</div>
<div class="section" id="advanced-topics">
<h1><a class="toc-backref" href="#id77">Advanced Topics</a></h1>
<p>The following discussions cover details of <cite>PyInstaller</cite> internal methods.
You should not need this level of detail for normal use,
but such details are helpful if you want to investigate
the <cite>PyInstaller</cite> code and possibly contribute to it,
as described in <a class="reference external" href="https://github.com/pyinstaller/pyinstaller/wiki/How-to-Contribute">How to Contribute</a>.</p>
<div class="section" id="the-bootstrap-process-in-detail">
<h2><a class="toc-backref" href="#id78">The Bootstrap Process in Detail</a></h2>
<p>There are many steps that must take place before the bundled
script can begin execution.
A summary of these steps was given in the Overview
(<a class="reference internal" href="#how-the-one-folder-program-works">How the One-Folder Program Works</a> and
<a class="reference internal" href="#how-the-one-file-program-works">How the One-File Program Works</a>).
Here is more detail to help you understand what the bootloader
does and how to figure out problems.</p>
<div class="section" id="bootloader">
<h3><a class="toc-backref" href="#id79">Bootloader</a></h3>
<p>The bootloader prepares everything for running Python code.
It begins the setup and then returns itself in another process.
This approach of using two processes allows a lot of flexibility
and is used in all bundles except one-folder mode in Windows.
So do not be surprised if you will see your bundled app
as  two processes in your system task manager.</p>
<p>What happens during execution of bootloader:</p>
<ol class="upperalpha">
<li><p class="first">First process: bootloader starts.</p>
<blockquote>
<ol class="arabic simple">
<li>If one-file mode, extract bundled files to <em>temppath</em><tt class="docutils literal">_MEI</tt><em>xxxxxx</em></li>
<li>Set/unset various environment variables,
e.g. override LD_LIBRARY_PATH on Linux or LIBPATH on AIX;
unset DYLD_LIBRARY_PATH on OSX.</li>
<li>Set up to handle signals for both processes.</li>
<li>Run the child process.</li>
<li>Wait for the child process to finish.</li>
<li>If one-file mode, delete <em>temppath</em><tt class="docutils literal">_MEI</tt><em>xxxxxx</em>.</li>
</ol>
</blockquote>
</li>
<li><p class="first">Second process: bootloader itself started as a child process.</p>
<blockquote>
<ol class="arabic simple">
<li>On Windows set the <a class="reference external" href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa374153(v=vs.85).aspx">activation context</a>.</li>
<li>Load the Python dynamic library.
The name of the dynamic library is embedded in the
executable file.</li>
<li>Initialize Python interpreter: set sys.path, sys.prefix, sys.executable.</li>
<li>Run python code.</li>
</ol>
</blockquote>
</li>
</ol>
<p>Running Python code requires several steps:</p>
<ol class="arabic simple">
<li>Run the Python initialization code which
prepares everything for running the user's main script.
The initialization code can use only the Python built-in modules
because the general import mechanism is not yet available.
It sets up the Python import mechanism to load modules
only from archives embedded in the executable.
It also adds the attributes <tt class="docutils literal">frozen</tt>
and <tt class="docutils literal">_MEIPASS</tt> to the <tt class="docutils literal">sys</tt> built-in module.</li>
<li>Execute any run-time hooks: first those specified by the
user, then any standard ones.</li>
<li>Install python &quot;egg&quot; files.
When a module is part of a zip file (.egg),
it has been bundled into the <tt class="docutils literal">./eggs</tt> directory.
Installing means appending .egg file names to <tt class="docutils literal">sys.path</tt>.
Python automatically detects whether an
item in <tt class="docutils literal">sys.path</tt> is a zip file or a directory.</li>
<li>Run the main script.</li>
</ol>
</div>
<div class="section" id="python-imports-in-a-bundled-app">
<h3><a class="toc-backref" href="#id80">Python imports in a bundled app</a></h3>
<p><cite>PyInstaller</cite> embeds compiled python code
(<tt class="docutils literal">.pyc</tt> files) within the executable.
<cite>PyInstaller</cite> injects its code into the
normal Python import mechanism.
Python allows this;
the support is described in <a class="reference external" href="http://www.python.org/dev/peps/pep-0302/">PEP 302</a>  &quot;New Import Hooks&quot;.</p>
<p>PyInstaller implements the PEP 302 specification for
importing built-in modules,
importing &quot;frozen&quot; modules (compiled python code
bundled with the app) and for C-extensions.
The code can be read in <tt class="docutils literal">./PyInstaller/loader/pyi_mod03_importers.py</tt>.</p>
<p>At runtime the PyInstaller PEP 302 hooks are appended
to the variable <tt class="docutils literal">sys.meta_path</tt>.
When trying to import modules the interpreter will
first try PEP 302 hooks in <tt class="docutils literal">sys.meta_path</tt>
before searching in <tt class="docutils literal">sys.path</tt>.
As a result, the Python interpreter
loads imported python modules from the archive embedded
in the bundled executable.</p>
<p>This is the resolution order of import statements
in a bundled app:</p>
<ol class="arabic simple">
<li>Is it a built-in module?
A list of built-in modules is in variable
<tt class="docutils literal">sys.builtin_module_names</tt>.</li>
<li>Is it a module embedded in the executable?
Then load it from embedded archive.</li>
<li>Is it a C-extension?
The app will try to find a file with name
<em>package.subpackage.module</em><tt class="docutils literal">.pyd</tt> or
<em>package.subpackage.module</em><tt class="docutils literal">.so</tt></li>
<li>Next examine paths in the <tt class="docutils literal">sys.path</tt>.
There could be any additional location with python modules
or <tt class="docutils literal">.egg</tt> filenames.</li>
<li>If the module was not found then
raise <tt class="docutils literal">ImportError</tt>.</li>
</ol>
</div>
</div>
<div class="section" id="the-toc-and-tree-classes">
<h2><a class="toc-backref" href="#id81">The TOC and Tree Classes</a></h2>
<p><cite>PyInstaller</cite> manages lists of files using the <tt class="docutils literal">TOC</tt>
(Table Of Contents) class.
It provides the <tt class="docutils literal">Tree</tt> class as a convenient way to build a <tt class="docutils literal">TOC</tt>
from a folder path.</p>
<div class="section" id="toc-class-table-of-contents">
<h3><a class="toc-backref" href="#id82">TOC Class (Table of Contents)</a></h3>
<p>Objects of the <tt class="docutils literal">TOC</tt> class are used as input to the classes created in
a spec file.
For example, the <tt class="docutils literal">scripts</tt> member of an Analysis object is a TOC
containing a list of scripts.
The <tt class="docutils literal">pure</tt> member is a TOC with a list of modules, and so on.</p>
<p>Basically a <tt class="docutils literal">TOC</tt> object contains a list of tuples of the form</p>
<blockquote>
<tt class="docutils literal">(</tt><em>name</em><tt class="docutils literal">,</tt><em>path</em><tt class="docutils literal">,</tt><em>typecode</em><tt class="docutils literal">)</tt></blockquote>
<p>In fact, it acts as an ordered set of tuples;
that is, it contains no duplicates
(where uniqueness is based on the <em>name</em> element of each tuple).
Within this constraint, a TOC preserves the order of tuples added to it.</p>
<p>A TOC behaves like a list and supports the same methods
such as appending, indexing, etc.
A TOC also behaves like a set, and supports taking differences and intersections.
In all of these operations a list of tuples can be used as one argument.
For example, the following expressions are equivalent ways to
add a file to the <tt class="docutils literal">a.datas</tt> member:</p>
<pre class="literal-block">
a.datas.append( [ ('README', 'src/README.txt', 'DATA' ) ] )
a.datas += [ ('README', 'src/README.txt', 'DATA' ) ]
</pre>
<p>Set-difference makes excluding modules quite easy. For example:</p>
<pre class="literal-block">
a.binaries - [('badmodule', None, None)]
</pre>
<p>is an expression that produces a new <tt class="docutils literal">TOC</tt> that is a copy of
<tt class="docutils literal">a.binaries</tt> from which any tuple named <tt class="docutils literal">badmodule</tt> has been removed.
The right-hand argument to the subtraction operator
is a list that contains one tuple
in which <em>name</em> is <tt class="docutils literal">badmodule</tt> and the <em>path</em> and <em>typecode</em> elements
are <tt class="docutils literal">None</tt>.
Because set membership is based on the <em>name</em> element of a tuple only,
it is not necessary to give accurate <em>path</em> and <em>typecode</em> elements when subtracting.</p>
<p>In order to add files to a TOC, you need to know the <em>typecode</em> values
and their related <em>path</em> values.
A <em>typecode</em> is a one-word string.
<cite>PyInstaller</cite> uses a number of <em>typecode</em> values internally,
but for the normal case you need to know only these:</p>
<table border="1" class="docutils">
<colgroup>
<col width="13%" />
<col width="33%" />
<col width="20%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head"><strong>typecode</strong></th>
<th class="head"><strong>description</strong></th>
<th class="head"><strong>name</strong></th>
<th class="head"><strong>path</strong></th>
</tr>
</thead>
<tbody valign="top">
<tr><td>'DATA'</td>
<td>Arbitrary files.</td>
<td>Run-time name.</td>
<td>Full path name in build.</td>
</tr>
<tr><td>'BINARY'</td>
<td>A shared library.</td>
<td>Run-time name.</td>
<td>Full path name in build.</td>
</tr>
<tr><td>'EXTENSION'</td>
<td>A binary extension to Python.</td>
<td>Run-time name.</td>
<td>Full path name in build.</td>
</tr>
<tr><td>'OPTION'</td>
<td>A Python run-time option.</td>
<td>Option code</td>
<td>ignored.</td>
</tr>
</tbody>
</table>
<p>The run-time name of a file will be used in the final bundle.
It may include path elements, for example <tt class="docutils literal">extras/mydata.txt</tt>.</p>
<p>A <tt class="docutils literal">BINARY</tt> file or an <tt class="docutils literal">EXTENSION</tt> file is assumed to be loadable, executable code,
for example a dynamic library.
The types are treated the same.
<tt class="docutils literal">EXTENSION</tt> is generally used for a Python extension module,
for example a module compiled by <a class="reference external" href="http://www.cython.org/">Cython</a>.
<cite>PyInstaller</cite> will examine either type of file for dependencies,
and if any are found, they are also included.</p>
</div>
<div class="section" id="the-tree-class">
<h3><a class="toc-backref" href="#id83">The Tree Class</a></h3>
<p>The Tree class is a way of creating a TOC that describes some or all of the
files within a directory:</p>
<blockquote>
<tt class="docutils literal">Tree(</tt><em>root</em><tt class="docutils literal">, prefix=</tt><em>run-time-folder</em><tt class="docutils literal">, excludes=</tt><em>string_list</em><tt class="docutils literal">, typecode=</tt><em>code</em> | <tt class="docutils literal">'DATA' )</tt></blockquote>
<ul class="simple">
<li>The <em>root</em> argument is a path string to a directory.
It may be absolute or relative to the spec file directory.</li>
<li>The <em>prefix</em> argument, if given, is a name for a subfolder
within the run-time folder to contain the tree files.
If you omit <em>prefix</em> or give <tt class="docutils literal">None</tt>,
the tree files will be at
the top level of the run-time folder.</li>
<li>The <em>excludes</em> argument, if given, is a list of one or more
strings that match files in the <em>root</em> that should be omitted from the Tree.
An item in the list can be either:<ul>
<li>a name, which causes files or folders with this basename to be excluded</li>
<li><tt class="docutils literal">*.ext</tt>, which causes files with this extension to be excluded</li>
</ul>
</li>
<li>The <em>typecode</em> argument, if given, specifies the TOC typecode string
that applies to all items in the Tree.
If omitted, the default is <tt class="docutils literal">DATA</tt>, which is appropriate for most cases.</li>
</ul>
<p>For example:</p>
<pre class="literal-block">
extras_toc = Tree('../src/extras', prefix='extras', excludes=['tmp','*.pyc'])
</pre>
<p>This creates <tt class="docutils literal">extras_toc</tt> as a TOC object that lists
all files from the relative path <tt class="docutils literal"><span class="pre">../src/extras</span></tt>,
omitting those that have the basename (or are in a folder named) <tt class="docutils literal">tmp</tt>
or that have the type <tt class="docutils literal">.pyc</tt>.
Each tuple in this TOC has:</p>
<ul class="simple">
<li>A <em>name</em> composed of <tt class="docutils literal">extras/</tt><em>filename</em>.</li>
<li>A <em>path</em> consisting of a complete, absolute path to that file in the <tt class="docutils literal"><span class="pre">../src/extras</span></tt> folder (relative to the location of the spec file).</li>
<li>A <em>typecode</em> of <tt class="docutils literal">DATA</tt> (by default).</li>
</ul>
<p>An example of creating a TOC listing some binary modules:</p>
<pre class="literal-block">
cython_mods = Tree( '..src/cy_mods', excludes=['*.pyx','*.py','*.pyc'], typecode='EXTENSION' )
</pre>
<p>This creates a TOC with a tuple for every file in the <tt class="docutils literal">cy_mods</tt> folder,
excluding any with the <tt class="docutils literal">.pyx</tt>, <tt class="docutils literal">.py</tt> or <tt class="docutils literal">.pyc</tt> suffixes
(so presumably collecting the <tt class="docutils literal">.pyd</tt> or <tt class="docutils literal">.so</tt> modules created by Cython).
Each tuple in this TOC has:</p>
<ul class="simple">
<li>Its own filename as <em>name</em> (no prefix; the file will be at the top level of the bundle).</li>
<li>A <em>path</em> as an absolute path to that file in <tt class="docutils literal"><span class="pre">../src/cy_mods</span></tt> relative to the spec file.</li>
<li>A <em>typecode</em> of <tt class="docutils literal">EXTENSION</tt> (<tt class="docutils literal">BINARY</tt> could be used as well).</li>
</ul>
</div>
</div>
<div class="section" id="inspecting-archives">
<h2><a class="toc-backref" href="#id84">Inspecting Archives</a></h2>
<p>An archive is a file that contains other files,
for example a <tt class="docutils literal">.tar</tt> file, a <tt class="docutils literal">.jar</tt> file, or a <tt class="docutils literal">.zip</tt> file.
Two kinds of archives are used in <cite>PyInstaller</cite>.
One is a ZlibArchive, which
allows Python modules to be stored efficiently and,
with some import hooks, imported directly.
The other, a CArchive, is similar to a <tt class="docutils literal">.zip</tt> file,
a general way of packing up (and optionally compressing) arbitrary blobs of data.
It gets its name from the fact that it can be manipulated easily from C
as well as from Python.
Both of these derive from a common base class, making it fairly easy to
create new kinds of archives.</p>
<div class="section" id="zlibarchive">
<h3><a class="toc-backref" href="#id85">ZlibArchive</a></h3>
<p>A ZlibArchive contains compressed <tt class="docutils literal">.pyc</tt> or <tt class="docutils literal">.pyo</tt> files.
The <tt class="docutils literal">PYZ</tt> class invocation in a spec file creates a ZlibArchive.</p>
<p>The table of contents in a ZlibArchive
is a Python dictionary that associates a key,
which is a member's name as given in an <tt class="docutils literal">import</tt> statement,
with a seek position and a length in the ZlibArchive.
All parts of a ZlibArchive are stored in the
<a class="reference external" href="http://docs.python.org/library/marshal">marshalled</a> format and so are platform-independent.</p>
<p>A ZlibArchive is used at run-time to import bundled python modules.
Even with maximum compression this works  faster than the normal import.
Instead of searching <tt class="docutils literal">sys.path</tt>, there's a lookup in the dictionary.
There are no directory operations and no
file to open (the file is already open).
There's just a seek, a read and a decompress.</p>
<p>A Python error trace will point to the source file from which the archive
entry was created (the <tt class="docutils literal">__file__</tt> attribute from the time the
<tt class="docutils literal">.pyc</tt> was compiled, captured and saved in the archive).
This will not tell your user anything useful,
but if they send you a Python error trace,
you can make sense of it.</p>
<p><img alt="ZlibArchiveImage" src="images/ZlibArchive.png" /></p>
</div>
<div class="section" id="carchive">
<h3><a class="toc-backref" href="#id86">CArchive</a></h3>
<p>A CArchive can contain any kind of file.
It's very much like a <tt class="docutils literal">.zip</tt> file.
They are easy to create in Python and easy to unpack from C code.
A CArchive can be appended to another file, such as
an ELF and COFF executable.
To allow this, the archive is made with its table of contents at the
end of the file, followed only by a cookie that tells where the
table of contents starts and
where the archive itself starts.</p>
<p>A CArchive can be embedded within another CArchive.
An inner archive can be opened and used in place,
without having to extract it.</p>
<p>Each table of contents entry has variable length.
The first field in the entry gives the length of the entry.
The last field is the name of the corresponding packed file.
The name is null terminated.
Compression is optional for each member.</p>
<p>There is also a type code associated with each member.
The type codes are used by the self-extracting executables.
If you're using a <tt class="docutils literal">CArchive</tt> as a <tt class="docutils literal">.zip</tt> file, you don't need to worry about the code.</p>
<p>The ELF executable format (Windows, Linux and some others) allows arbitrary
data to be concatenated to the end of the executable without disturbing its
functionality. For this reason, a CArchive's Table of Contents is
at the end of the archive. The executable can open itself as a binary
file, seek to the end and 'open' the CArchive.</p>
<p><img alt="CArchiveImage" src="images/CArchive.png" /></p>
</div>
<div class="section" id="using-pyi-archive-viewer">
<h3><a class="toc-backref" href="#id87">Using pyi-archive_viewer</a></h3>
<p>Use the <tt class="docutils literal"><span class="pre">pyi-archive_viewer</span></tt> command to inspect any type of archive:</p>
<blockquote>
<tt class="docutils literal"><span class="pre">pyi-archive_viewer</span></tt> <em>archivefile</em></blockquote>
<p>With this command you can examine the contents of any archive built with
<cite>PyInstaller</cite> (a <tt class="docutils literal">PYZ</tt> or <tt class="docutils literal">PKG</tt>), or any executable (<tt class="docutils literal">.exe</tt> file
or an ELF or COFF binary).
The archive can be navigated using these commands:</p>
<dl class="docutils">
<dt>O <em>name</em></dt>
<dd>Open the embedded archive <em>name</em> (will prompt if omitted).
For example when looking in a one-file executable, you
can open the <tt class="docutils literal">outPYZ.pyz</tt> archive inside it.</dd>
<dt>U</dt>
<dd>Go up one level (back to viewing the containing archive).</dd>
<dt>X <em>name</em></dt>
<dd>Extract <em>name</em> (will prompt if omitted).
Prompts for an output filename.
If none given, the member is extracted to stdout.</dd>
<dt>Q</dt>
<dd>Quit.</dd>
</dl>
<p>The <tt class="docutils literal"><span class="pre">pyi-archive_viewer</span></tt> command has these options:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
<td>Show help.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-l</span>, <span class="option">--log</span></kbd></td>
<td>Quick contents log.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-b</span>, <span class="option">--brief</span></kbd></td>
<td>Print a python evaluable list of contents filenames.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-r</span>, <span class="option">--recursive</span></kbd></td>
</tr>
<tr><td>&nbsp;</td><td>Used with -l or -b, applies recursive behaviour.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="inspecting-executables">
<h2><a class="toc-backref" href="#id88">Inspecting Executables</a></h2>
<p>You can inspect any executable file with <tt class="docutils literal"><span class="pre">pyi-bindepend</span></tt>:</p>
<blockquote>
<tt class="docutils literal"><span class="pre">pyi-bindepend</span></tt> <em>executable_or_dynamic_library</em></blockquote>
<p>The <tt class="docutils literal"><span class="pre">pyi-bindepend</span></tt> command analyzes the executable or DLL you name
and writes to stdout all its binary dependencies.
This is handy to find out which DLLs are required by
an executable or by another DLL.</p>
<p><tt class="docutils literal"><span class="pre">pyi-bindepend</span></tt> is used by <cite>PyInstaller</cite> to
follow the chain of dependencies of binary extensions
during Analysis.</p>
</div>
<div class="section" id="creating-a-reproducible-build">
<h2><a class="toc-backref" href="#id89">Creating a Reproducible Build</a></h2>
<p>In certain cases it is important that when you build the same application twice,
using exactly the same set of dependencies,
the two bundles should be exactly, bit-for-bit identical.</p>
<p>That is not the case normally.
Python uses a random hash to make dicts and other hashed types,
and this affects compiled byte-code as well as <cite>PyInstaller</cite>
internal data structures.
As a result, two builds may not produce bit-for-bit identical results
even when all the components of the application bundle are the same
and the two applications execute in identical ways.</p>
<p>You can assure that a build will produce the same bits
by setting the <tt class="docutils literal">PYTHONHASHSEED</tt> environment variable to a known
integer value before running <cite>PyInstaller</cite>.
This forces Python to use the same random hash sequence until
<tt class="docutils literal">PYTHONHASHSEED</tt> is unset or set to <tt class="docutils literal">'random'</tt>.
For example, execute <cite>PyInstaller</cite> in a script such as
the following (for Linux and OS X):</p>
<pre class="literal-block">
# set seed to a known repeatable integer value
PYTHONHASHSEED=1
export PYTHONHASHSEED
# create one-file build as myscript
pyinstaller myscript.spec
# make checksum
cksum dist/myscript/myscript | awk '{print $1}' &gt; dist/myscript/checksum.txt
# let Python be unpredictable again
unset PYTHONHASHSEED
</pre>
</div>
</div>
<div class="section" id="understanding-pyinstaller-hooks">
<h1><a class="toc-backref" href="#id90">Understanding PyInstaller Hooks</a></h1>
<p>In summary, a &quot;hook&quot; file extends <cite>PyInstaller</cite> to adapt it to
the special needs and methods used by a Python package.
The word &quot;hook&quot; is used for two kinds of files.
A <em>runtime</em> hook helps the bootloader to launch an app.
For more on runtime hooks, see <a class="reference internal" href="#changing-runtime-behavior">Changing Runtime Behavior</a>.
Other hooks run while an app is being analyzed.
They help the Analysis phase find needed files.</p>
<p>The majority of Python packages use normal methods of importing
their dependencies, and <cite>PyInstaller</cite> locates all their files without difficulty.
But some packages make unusual uses of the Python import mechanism,
or make clever changes to the import system at runtime.
For this or other reasons, <cite>PyInstaller</cite> cannot reliably find
all the needed files, or may include too many files.
A hook can tell about additional source files or data files to import,
or files not to import.</p>
<p>A hook file is a Python script, and can use all Python features.
It can also import helper methods from <tt class="docutils literal">PyInstaller.utils.hooks</tt>
and useful variables from <tt class="docutils literal">PyInstaller.compat</tt>.
These helpers are documented below.</p>
<p>The name of a hook file is <tt class="docutils literal">hook-</tt><em>full-import-name</em><tt class="docutils literal">.py</tt>,
where <em>full-import-name</em> is
the fully-qualified name of an imported script or module.
You can browse through the existing hooks in the
<tt class="docutils literal">hooks</tt> folder of the <cite>PyInstaller</cite> distribution folder
and see the names of the packages for which hooks have been written.
For example <tt class="docutils literal"><span class="pre">hook-PyQt5.QtCore.py</span></tt> is a hook file telling
about hidden imports needed by the module <tt class="docutils literal">PyQt5.QtCore</tt>.
When your script contains <tt class="docutils literal">import PyQt5.QtCore</tt>
(or <tt class="docutils literal">from PyQt5 import QtCore</tt>),
Analysis notes that <tt class="docutils literal"><span class="pre">hook-PyQt5.QtCore.py</span></tt> exists, and will call it.</p>
<p>Many hooks consist of only one statement, an assignment to <tt class="docutils literal">hiddenimports</tt>.
For example, the hook for the <a class="reference external" href="http://www.dnspython.org/">dnspython</a> package, called
<tt class="docutils literal"><span class="pre">hook-dns.rdata.py</span></tt>, has only this statement:</p>
<pre class="literal-block">
hiddenimports = [
    &quot;dns.rdtypes.*&quot;,
    &quot;dns.rdtypes.ANY.*&quot;
]
</pre>
<p>When Analysis sees <tt class="docutils literal">import dns.rdata</tt> or <tt class="docutils literal">from dns import rdata</tt>
it calls <tt class="docutils literal"><span class="pre">hook-dns.rdata.py</span></tt> and examines its value
of <tt class="docutils literal">hiddenimports</tt>.
As a result, it is as if your source script also contained:</p>
<pre class="literal-block">
import dns.rdtypes.*
import dsn.rdtypes.ANY.*
</pre>
<p>A hook can also cause the addition of data files,
and it can cause certain files to <em>not</em> be imported.
Examples of these actions are shown below.</p>
<p>When the module that needs these hidden imports is useful only to your project,
store the hook file(s) somewhere near your source file.
Then specify their location to the <tt class="docutils literal">pyinstaller</tt> or <tt class="docutils literal"><span class="pre">pyi-makespec</span></tt>
command with the <tt class="docutils literal"><span class="pre">--additional-hooks-dir=</span></tt> option.
If the hook file(s) are at the same level as the script,
the command could be simply:</p>
<pre class="literal-block">
pyinstaller --additional-hooks-dir=. myscript.py
</pre>
<p>If you write a hook for a module used by others,
please send us the hook file so we can make it available.</p>
<div class="section" id="how-a-hook-is-loaded">
<h2><a class="toc-backref" href="#id91">How a Hook Is Loaded</a></h2>
<p>A hook is a module named <tt class="docutils literal">hook-</tt><em>full-import-name</em><tt class="docutils literal">.py</tt>
in a folder where the Analysis object looks for hooks.
Each time Analysis detects an import, it looks for a hook file with
a matching name.
When one is found, Analysis imports the hook's code into a Python namespace.
This results in the execution of all top-level statements in the hook source,
for example import statements, assignments to global names, and
function definitions.
The names defined by these statements are visible to Analysis
as attributes of the namespace.</p>
<p>Thus a hook is a normal Python script and can use all normal Python facilities.
For example it could test <tt class="docutils literal">sys.version</tt> and adjust its
assignment to <tt class="docutils literal">hiddenimports</tt> based on that.
There are over 150 hooks in the <cite>PyInstaller</cite> installation.
You are welcome to browse through them for examples.</p>
<div class="section" id="hook-global-variables">
<h3><a class="toc-backref" href="#id92">Hook Global Variables</a></h3>
<p>A majority of the existing hooks consist entirely of assignments of
values to one or more of the following global variables.
If any of these are defined by the hook, Analysis takes their values and
applies them to the bundle being created.</p>
<dl class="docutils">
<dt><tt class="docutils literal">hiddenimports</tt></dt>
<dd><p class="first">A list of module names (relative or absolute) that should
be part of the bundled app.
This has the same effect as the <tt class="docutils literal"><span class="pre">--hidden-import</span></tt> command line option,
but it can contain a list of names and is applied automatically
only when the hooked module is imported.
Example:</p>
<pre class="last literal-block">
hiddenimports = ['_proxy', 'utils', 'defs']
</pre>
</dd>
<dt><tt class="docutils literal">excludedimports</tt></dt>
<dd><p class="first">A list of absolute module names that should
<em>not</em> be part of the bundled app.
If an excluded module is imported only by the hooked module or one
of its sub-modules, the excluded name and its sub-modules
will not be part of the bundle.
(If an excluded name is explicitly imported in the
source file or some other module, it will be kept.)
Several hooks use this to prevent automatic inclusion of
the <tt class="docutils literal">tkinter</tt> module. Example:</p>
<pre class="last literal-block">
excludedimports = [modname_tkinter]
</pre>
</dd>
<dt><tt class="docutils literal">datas</tt></dt>
<dd><p class="first">A list of files to bundle with the app as data.
Each entry in the list is a tuple containing two strings.
The first string specifies a file (or file &quot;glob&quot;) in this system,
and the second specifies the name(s) the file(s) are to have in
the bundle.
(This is the same format as used for the <tt class="docutils literal">datas=</tt> argument,
see <a class="reference internal" href="#adding-data-files">Adding Data Files</a>.)
Example:</p>
<pre class="literal-block">
datas = [ ('/usr/share/icons/education_*.png', 'icons') ]
</pre>
<p>If you need to collect multiple directories or nested directories,
you can use helper functions from the <tt class="docutils literal">PyInstaller.hooks.utils</tt> module
(see below) to create this list, for example:</p>
<pre class="literal-block">
datas = collect_data_files('submodule1')
datas+= collect_data_files('submodule2')
</pre>
<p class="last">In rare cases you may need to apply logic to locate
particular files within the file system,
for example because the files are
in different places on different platforms or under different versions.
Then you can write a <tt class="docutils literal">hook()</tt> function as described
below under <cite>The ``hook(hook_api)`</cite> Function`_.</p>
</dd>
<dt><tt class="docutils literal">binaries</tt></dt>
<dd><p class="first">A list of files or directories to bundle as binaries.
The format is the same as <tt class="docutils literal">datas</tt> (tuples with strings that
specify the source and the destination).
Binaries is a special case of <tt class="docutils literal">datas</tt>, in that PyInstaller will
check each file to see if it depends on other dynamic libraries.
Example:</p>
<pre class="literal-block">
binaries = [ ('C:\\Windows\\System32\\*.dll', 'dlls') ]
</pre>
<p>Many hooks use helpers from the <tt class="docutils literal">PyInstaller.hooks.utils</tt> module
to create this list (see below):</p>
<pre class="last literal-block">
binaries = collect_dynamic_libs('zmq')
</pre>
</dd>
</dl>
</div>
<div class="section" id="useful-items-in-pyinstaller-compat">
<h3><a class="toc-backref" href="#id93">Useful Items in <tt class="docutils literal">PyInstaller.compat</tt></a></h3>
<p>A hook may import the following names from <tt class="docutils literal">PyInstaller.compat</tt>,
for example:</p>
<pre class="literal-block">
from PyInstaller.compat import modname_tkinter, is_win
</pre>
<dl class="docutils">
<dt><tt class="docutils literal">is_py2</tt>:</dt>
<dd>True when the active Python is version 2.7.</dd>
<dt><tt class="docutils literal">is_py3</tt>:</dt>
<dd>True when the active Python is version 3.X.</dd>
<dt><tt class="docutils literal">is_py34</tt>, <tt class="docutils literal">is_py35</tt>, <tt class="docutils literal">is_py36</tt>:</dt>
<dd>True when the current version of Python is at least 3.4, 3.5 or 3.6 respectively.</dd>
<dt><tt class="docutils literal">is_win</tt>:</dt>
<dd>True in a Windows system.</dd>
<dt><tt class="docutils literal">is_cygwin</tt>:</dt>
<dd>True when <tt class="docutils literal"><span class="pre">sys.platform=='cygwin'</span></tt>.</dd>
<dt><tt class="docutils literal">is_darwin</tt>:</dt>
<dd>True in Mac OS X.</dd>
<dt><tt class="docutils literal">is_linux</tt>:</dt>
<dd>True in any Linux system (<tt class="docutils literal"><span class="pre">sys.platform.startswith('linux')</span></tt>).</dd>
<dt><tt class="docutils literal">is_solar</tt>:</dt>
<dd>True in Solaris.</dd>
<dt><tt class="docutils literal">is_aix</tt>:</dt>
<dd>True in AIX.</dd>
<dt><tt class="docutils literal">is_freebsd</tt>:</dt>
<dd>True in FreeBSD.</dd>
<dt><tt class="docutils literal">is_venv</tt>:</dt>
<dd>True in any virtual environment (either virtualenv or venv).</dd>
<dt><tt class="docutils literal">base_prefix</tt>:</dt>
<dd>String, the correct path to the base Python installation,
whether the installation is native or a virtual environment.</dd>
<dt><tt class="docutils literal">modname_tkinter</tt>:</dt>
<dd><p class="first">String, <tt class="docutils literal">Tkinter</tt> in Python 2.7 but <tt class="docutils literal">tkinter</tt> in Python 3.
To prevent an unnecessary import of Tkinter, write:</p>
<pre class="last literal-block">
from PyInstaller.compat import modname_tkinter
excludedimports = [ modname_tkinter ]
</pre>
</dd>
<dt><tt class="docutils literal">EXTENSION_SUFFIXES</tt>:</dt>
<dd>List of Python C-extension file suffixes. Used for finding all
binary dependencies in a folder; see <tt class="docutils literal"><span class="pre">hook-cryptography.py</span></tt> for an example.</dd>
</dl>
</div>
<div class="section" id="useful-items-in-pyinstaller-utils-hooks">
<h3><a class="toc-backref" href="#id94">Useful Items in <tt class="docutils literal">PyInstaller.utils.hooks</tt></a></h3>
<p>A hook may import useful functions from <tt class="docutils literal">PyInstaller.utils.hooks</tt>.
Use a fully-qualified import statement, for example:</p>
<pre class="literal-block">
from PyInstaller.utils.hooks import collect_data_files, eval_statement
</pre>
<p>The <tt class="docutils literal">PyInstaller.utils.hooks</tt> functions listed here are generally useful
and used in a number of existing hooks.
There are several more functions besides these that serve the needs
of specific hooks, such as hooks for PyQt4/5.
You are welcome to read the <tt class="docutils literal">PyInstaller.utils.hooks</tt> module
(and read the existing hooks that import from it) to get code and ideas.</p>
<dl class="docutils">
<dt><tt class="docutils literal">exec_statement( 'statement' )</tt>:</dt>
<dd><p class="first">Execute a single Python statement in an externally-spawned interpreter
and return the standard output that results, as a string.
Examples:</p>
<pre class="last literal-block">
tk_version = exec_statement(
   &quot;from _tkinter import TK_VERSION; print(TK_VERSION)&quot;
   )

mpl_data_dir = exec_statement(
   &quot;import matplotlib; print(matplotlib._get_data_path())&quot;
   )
datas = [ (mpl_data_dir, &quot;&quot;) ]
</pre>
</dd>
<dt><tt class="docutils literal">eval_statement( 'statement' )</tt>:</dt>
<dd><p class="first">Execute a single Python statement in an externally-spawned interpreter.
If the resulting standard output text is not empty, apply
the <tt class="docutils literal">eval()</tt> function to it; else return None. Example:</p>
<pre class="last literal-block">
databases = eval_statement('''
   import sqlalchemy.databases
   print(sqlalchemy.databases.__all__)
   ''')
for db in databases:
   hiddenimports.append(&quot;sqlalchemy.databases.&quot; + db)
</pre>
</dd>
<dt><tt class="docutils literal">is_module_satisfies( requirements, version=None, <span class="pre">version_attr='__version__'</span> )</tt>:</dt>
<dd><p class="first">Check that the named module (fully-qualified) exists and satisfies the
given requirement. Example:</p>
<pre class="literal-block">
if is_module_satisfies('sqlalchemy &gt;= 0.6'):
</pre>
<p>This function provides robust version checking based on the same low-level
algorithm used by <tt class="docutils literal">easy_install</tt> and <tt class="docutils literal">pip</tt>, and should always be
used in preference to writing your own comparison code.
In particular, version strings should never be compared lexicographically
(except for exact equality).
For example <tt class="docutils literal">'00.5' &gt; '0.6'</tt> returns True, which is not the desired result.</p>
<p>The <tt class="docutils literal">requirements</tt> argument uses the same syntax as supported by
the <a class="reference external" href="https://pythonhosted.org/setuptools/pkg_resources.html#requirements-parsing">Package resources</a> module of setup tools (follow the link to
see the supported syntax).</p>
<p>The optional <tt class="docutils literal">version</tt> argument is is a PEP0440-compliant,
dot-delimited version specifier such as <tt class="docutils literal"><span class="pre">'3.14-rc5'</span></tt>.</p>
<p>When the package being queried has been installed by <tt class="docutils literal">easy_install</tt>
or <tt class="docutils literal">pip</tt>, the existing setup tools machinery is used to perform the test
and the <tt class="docutils literal">version</tt> and <tt class="docutils literal">version_attr</tt> arguments are ignored.</p>
<p>When that is not the case, the <tt class="docutils literal">version</tt> argument is taken as the
installed version of the package
(perhaps obtained by interrogating the package in some other way).
When <tt class="docutils literal">version</tt> is <tt class="docutils literal">None</tt>, the named package is imported into a
subprocess, and the <tt class="docutils literal">__version__</tt> value of that import is tested.
If the package uses some other name than <tt class="docutils literal">__version__</tt> for its version
global, that name can be passed as the <tt class="docutils literal">version_attr</tt> argument.</p>
<p class="last">For more details and examples refer to the function's doc-string, found
in <tt class="docutils literal">Pyinstaller/utils/hooks/__init__.py</tt>.</p>
</dd>
<dt><tt class="docutils literal">collect_submodules( <span class="pre">'package-name',</span> subdir=None, pattern=None )</tt>:</dt>
<dd><p class="first">Returns a list of strings that specify all the modules in a package,
ready to be assigned to the <tt class="docutils literal">hiddenimports</tt> global.
Returns an empty list when <tt class="docutils literal">package</tt> does not name a package
(a package is defined as a module that contains a <tt class="docutils literal">__path__</tt> attribute).</p>
<p><tt class="docutils literal">subdir</tt>, if given, names a relative subdirectory in the package,
used in the case where a package imports modules at runtime from a
directory lacking <tt class="docutils literal">__init__.py</tt>.
The <tt class="docutils literal">pattern</tt>, if given, is a string that may be contained in the
names of modules.
Only modules containing the pattern will be returned.
Example:</p>
<pre class="last literal-block">
hiddenimports = collect_submodules( 'PIL', pattern='ImagePlugin' )
</pre>
</dd>
<dt><tt class="docutils literal">collect_data_files( <span class="pre">'module-name',</span> subdir=None, include_py_files=False )</tt>:</dt>
<dd><p class="first">Returns a list of (source, dest) tuples for all non-Python (i.e. data)
files found in <em>module-name</em>, ready to be assigned to the <tt class="docutils literal">datas</tt> global.
<em>module-name</em> is the fully-qualified name of a module or
package (but not a zipped &quot;egg&quot;).
The function uses <tt class="docutils literal">os.walk()</tt> to visit the module directory recursively.
<tt class="docutils literal">subdir</tt>, if given, restricts the search to a relative subdirectory.</p>
<p class="last">Normally Python executable files (ending in <tt class="docutils literal">.py</tt>, <tt class="docutils literal">.pyc</tt>, etc.)
are not collected. Pass <tt class="docutils literal">include_py_files=True</tt> to collect those
files as well.
(This can be used with routines such as those in <tt class="docutils literal">pkgutil</tt> that
search a directory for Python executable files and load them as
extensions or plugins.)</p>
</dd>
<dt><tt class="docutils literal">collect_dynamic_libs( <span class="pre">'module-name'</span> )</tt>:</dt>
<dd><p class="first">Returns a list of (source, dest) tuples for all the dynamic libs
present in a module directory.
The list is ready to be assigned to the <tt class="docutils literal">binaries</tt> global variable.
The function uses <tt class="docutils literal">os.walk()</tt> to examine all files in the
module directory recursively.
The name of each file found is tested against the likely patterns for
a dynamic lib: <tt class="docutils literal">*.dll</tt>, <tt class="docutils literal">*.dylib</tt>, <tt class="docutils literal"><span class="pre">lib*.pyd</span></tt>, and <tt class="docutils literal"><span class="pre">lib*.so</span></tt>.
Example:</p>
<pre class="last literal-block">
binaries = collect_dynamic_libs( 'enchant' )
</pre>
</dd>
<dt><tt class="docutils literal">get_module_file_attribute( <span class="pre">'module-name'</span> )</tt>:</dt>
<dd><p class="first">Return the absolute path to <em>module-name</em>, a fully-qualified module name.
Example:</p>
<pre class="last literal-block">
nacl_dir = os.path.dirname(get_module_file_attribute('nacl'))
</pre>
</dd>
<dt><tt class="docutils literal">get_package_paths( <span class="pre">'package-name'</span> )</tt>:</dt>
<dd><p class="first">Given the name of a package, return a tuple.
The first element is the absolute path to the folder where the package is stored.
The second element is the absolute path to the named package.
For example, if <tt class="docutils literal">pkg.subpkg</tt> is stored in <tt class="docutils literal">/abs/Python/lib</tt>
the result of:</p>
<pre class="literal-block">
get_package_paths( 'pkg.subpkg' )
</pre>
<p class="last">is the tuple, <tt class="docutils literal">( '/abs/Python/lib', '/abs/Python/lib/pkg/subpkg' )</tt></p>
</dd>
<dt><tt class="docutils literal">copy_metadata( <span class="pre">'package-name'</span> )</tt>:</dt>
<dd><p class="first">Given the name of a package, return the name of its distribution
metadata folder as a list of tuples ready to be assigned
(or appended) to the <tt class="docutils literal">datas</tt> global variable.</p>
<p class="last">Some packages rely on metadata files accessed through the
<tt class="docutils literal">pkg_resources</tt> module.
Normally <cite>PyInstaller</cite> does not include these metadata files.
If a package fails without them, you can use this
function in a hook file to easily add them to the bundle.
The tuples in the returned list have two strings.
The first is the full pathname to a folder in this system.
The second is the folder name only.
When these tuples are added to <tt class="docutils literal">datas</tt>,
the folder will be bundled at the top level.
If <em>package-name</em> does not have metadata, an
AssertionError exception is raised.</p>
</dd>
<dt><tt class="docutils literal">get_homebrew_path( <span class="pre">formula=''</span> )</tt>:</dt>
<dd>Return the homebrew path to the named formula, or to the
global prefix when formula is omitted. Returns None if
not found.</dd>
<dt><tt class="docutils literal">django_find_root_dir()</tt>:</dt>
<dd>Return the path to the top-level Python package containing
the Django files, or None if nothing can be found.</dd>
<dt><tt class="docutils literal">django_dottedstring_imports( <span class="pre">'django-root-dir'</span> )</tt></dt>
<dd>Return a list of all necessary Django modules specified in
the Django settings.py file, such as the
<tt class="docutils literal">Django.settings.INSTALLED_APPS</tt> list and many others.</dd>
</dl>
</div>
<div class="section" id="the-hook-hook-api-function">
<h3><a class="toc-backref" href="#id95">The <tt class="docutils literal">hook(hook_api)</tt> Function</a></h3>
<p>In addition to, or instead of, setting global values,
a hook may define a function <tt class="docutils literal">hook(hook_api)</tt>.
A <tt class="docutils literal">hook()</tt> function should only be needed if the hook
needs to apply sophisticated logic or to make a complex
search of the source machine.</p>
<p>The Analysis object calls the function and passes it a <tt class="docutils literal">hook_api</tt> object
which has the following immutable properties:</p>
<dl class="docutils">
<dt><tt class="docutils literal">__name__</tt>:</dt>
<dd>The fully-qualified name of the module that caused the
hook to be called, e.g., <tt class="docutils literal">six.moves.tkinter</tt>.</dd>
<dt><tt class="docutils literal">__file__</tt>:</dt>
<dd><p class="first">The absolute path of the module. If it is:</p>
<blockquote class="last">
<ul class="simple">
<li>A standard (rather than namespace) package, this is the absolute path
of this package's directory.</li>
<li>A namespace (rather than standard) package, this is the abstract
placeholder <tt class="docutils literal">-</tt>.</li>
<li>A non-package module or C extension, this is the absolute path of the
corresponding file.</li>
</ul>
</blockquote>
</dd>
<dt><tt class="docutils literal">__path__</tt>:</dt>
<dd>A list of the absolute paths of all directories comprising the module
if it is a package, or <tt class="docutils literal">None</tt>. Typically the list contains only the
absolute path of the package's directory.</dd>
</dl>
<p>The <tt class="docutils literal">hook_api</tt> object also offers the following methods:</p>
<dl class="docutils">
<dt><tt class="docutils literal">add_imports( *names )</tt>:</dt>
<dd>The <tt class="docutils literal">names</tt> argument may be a single string or a list of strings
giving the fully-qualified name(s) of modules to be imported.
This has the same effect as adding the names to the <tt class="docutils literal">hiddenimports</tt> global.</dd>
<dt><tt class="docutils literal">del_imports( *names )</tt>:</dt>
<dd>The <tt class="docutils literal">names</tt> argument may be a single string or a list of strings,
giving the fully-qualified name(s) of modules that are not
to be included if they are imported only by the hooked module.
This has the same effect as adding names to the <tt class="docutils literal">excludedimports</tt> global.</dd>
<dt><tt class="docutils literal">add_datas( tuple_list )</tt>:</dt>
<dd>The <tt class="docutils literal">tuple_list</tt> argument has the format used with the <tt class="docutils literal">datas</tt> global
variable. This call has the effect of adding items to that list.</dd>
<dt><tt class="docutils literal">add_binaries( tuple_list )</tt>:</dt>
<dd>The <tt class="docutils literal">tuple_list</tt> argument has the format used with the <tt class="docutils literal">binaries</tt>
global variable. This call has the effect of adding items to that list.</dd>
</dl>
<p>The <tt class="docutils literal">hook()</tt> function can add, remove or change included files using the
above methods of <tt class="docutils literal">hook_api</tt>.
Or, it can simply set values in the four global variables, because
these will be examined after <tt class="docutils literal">hook()</tt> returns.</p>
</div>
<div class="section" id="the-pre-find-module-path-pfmp-api-method">
<h3><a class="toc-backref" href="#id96">The <tt class="docutils literal">pre_find_module_path( pfmp_api )</tt> Method</a></h3>
<p>You may write a hook with the special function <tt class="docutils literal">pre_find_module_path( pfmp_api )</tt>.
This method is called when the hooked module name is first seen
by Analysis, before it has located the path to that module or package
(hence the name &quot;pre-find-module-path&quot;).</p>
<p>Hooks of this type are only recognized if they are stored in
a sub-folder named <tt class="docutils literal">pre_find_module_path</tt> in a hooks folder,
either in the distributed hooks folder or an <tt class="docutils literal"><span class="pre">--additional-hooks-dir</span></tt> folder.
You may have normal hooks as well as hooks of this type for the same module.
For example <cite>PyInstaller</cite> includes both a <tt class="docutils literal"><span class="pre">hooks/hook-distutils.py</span></tt>
and also a <tt class="docutils literal"><span class="pre">hooks/pre_find_module_path/hook-distutils.py</span></tt>.</p>
<p>The <tt class="docutils literal">pfmp_api</tt> object that is passed has the following immutable attribute:</p>
<dl class="docutils">
<dt><tt class="docutils literal">module_name</tt>:</dt>
<dd>A string, the fully-qualified name of the hooked module.</dd>
</dl>
<p>The <tt class="docutils literal">pfmp_api</tt> object has one mutable attribute, <tt class="docutils literal">search_dirs</tt>.
This is a list of strings that specify the absolute path, or paths,
that will be searched for the hooked module.
The paths in the list will be searched in sequence.
The <tt class="docutils literal">pre_find_module_path()</tt> function may replace or change
the contents of <tt class="docutils literal">pfmp_api.search_dirs</tt>.</p>
<p>Immediately after return from <tt class="docutils literal">pre_find_module_path()</tt>, the contents
of <tt class="docutils literal">search_dirs</tt> will be used to find and analyze the module.</p>
<p>For an example of use,
see the file <tt class="docutils literal"><span class="pre">hooks/pre_find_module_path/hook-distutils.py</span></tt>.
It uses this method to redirect a search for distutils when
<cite>PyInstaller</cite> is executing in a virtual environment.</p>
</div>
<div class="section" id="the-pre-safe-import-module-psim-api-method">
<h3><a class="toc-backref" href="#id97">The <tt class="docutils literal">pre_safe_import_module( psim_api )</tt> Method</a></h3>
<p>You may write a hook with the special function <tt class="docutils literal">pre_safe_import_module( psim_api )</tt>.
This method is called after the hooked module has been found,
but <em>before</em> it and everything it recursively imports is added
to the &quot;graph&quot; of imported modules.
Use a pre-safe-import hook in the unusual case where:</p>
<ul class="simple">
<li>The script imports <em>package.dynamic-name</em></li>
<li>The <em>package</em> exists</li>
<li>however, no module <em>dynamic-name</em> exists at compile time (it will be defined somehow at run time)</li>
</ul>
<p>You use this type of hook to make dynamically-generated names known to PyInstaller.
PyInstaller will not try to locate the dynamic names, fail, and report them as missing.
However, if there are normal hooks for these names, they will be called.</p>
<p>Hooks of this type are only recognized if they are stored in a sub-folder
named <tt class="docutils literal">pre_safe_import_module</tt> in a hooks folder,
either in the distributed hooks folder or an <tt class="docutils literal"><span class="pre">--additional-hooks-dir</span></tt> folder.
(See the distributed <tt class="docutils literal">hooks/pre_safe_import_module</tt> folder for examples.)</p>
<p>You may have normal hooks as well as hooks of this type for the same module.
For example the distributed system has both a <tt class="docutils literal"><span class="pre">hooks/hook-gi.repository.GLib.py</span></tt>
and also a <tt class="docutils literal"><span class="pre">hooks/pre_safe_import_module/hook-gi.repository.GLib.py</span></tt>.</p>
<p>The <tt class="docutils literal">psim_api</tt> object offers the following attributes,
all of which are immutable (an attempt to change one raises an exception):</p>
<dl class="docutils">
<dt><tt class="docutils literal">module_basename</tt>:</dt>
<dd>String, the unqualified name of the hooked module, for example <tt class="docutils literal">text</tt>.</dd>
<dt><tt class="docutils literal">module_name</tt>:</dt>
<dd>String, the fully-qualified name of the hooked module, for example
<tt class="docutils literal">email.mime.text</tt>.</dd>
<dt><tt class="docutils literal">module_graph</tt>:</dt>
<dd>The module graph representing all imports processed so far.</dd>
<dt><tt class="docutils literal">parent_package</tt>:</dt>
<dd>If this module is a top-level module of its package, <tt class="docutils literal">None</tt>.
Otherwise, the graph node that represents the import of the
top-level module.</dd>
</dl>
<p>The last two items, <tt class="docutils literal">module_graph</tt> and <tt class="docutils literal">parent_package</tt>,
are related to the module-graph, the internal data structure used by
<cite>PyInstaller</cite> to document all imports.
Normally you do not need to know about the module-graph.</p>
<p>The <tt class="docutils literal">psim_api</tt> object also offers the following methods:</p>
<dl class="docutils">
<dt><tt class="docutils literal">add_runtime_module( fully_qualified_name )</tt>:</dt>
<dd><p class="first">Use this method to add an imported module whose name may not
appear in the source because it is dynamically defined at run-time.
This is useful to make the module known to <cite>PyInstaller</cite> and avoid misleading warnings.
A typical use applies the name from the <tt class="docutils literal">psim_api</tt>:</p>
<pre class="last literal-block">
psim_api.add_runtime_module( psim_api.module_name )
</pre>
</dd>
<dt><tt class="docutils literal">add_alias_module( real_module_name, alias_module_name )</tt>:</dt>
<dd><tt class="docutils literal">real_module_name</tt> is the fully-qualifed name of an existing
module, one that has been or could be imported by name
(it will be added to the graph if it has not already been imported).
<tt class="docutils literal">alias_module_name</tt> is a name that might be referenced in the
source file but should be treated as if it were <tt class="docutils literal">real_module_name</tt>.
This method ensures that if <cite>PyInstaller</cite> processes an import of
<tt class="docutils literal">alias_module_name</tt> it will use <tt class="docutils literal">real_module_name</tt>.</dd>
<dt><tt class="docutils literal">append_package_path( directory )</tt>:</dt>
<dd>The hook can use this method to add a package path
to be searched by <cite>PyInstaller</cite>, typically an import
path that the imported module would add dynamically to
the path if the module was executed normally.
<tt class="docutils literal">directory</tt> is a string, a pathname to add to the
<tt class="docutils literal">__path__</tt> attribute.</dd>
</dl>
</div>
</div>
</div>
<div class="section" id="building-the-bootloader">
<h1><a class="toc-backref" href="#id98">Building the Bootloader</a></h1>
<p>PyInstaller comes with binary bootloaders for most platforms in
the <tt class="docutils literal">bootloader</tt> folder of the distribution folder.
For most cases, these precompiled bootloaders are all you need.</p>
<p>If there is no precompiled bootloader for your platform,
or if you want to modify the bootloader source,
you need to build the bootloader.</p>
<p>For</p>
<ul class="simple">
<li><tt class="docutils literal">cd</tt> into the distribution folder.</li>
<li><tt class="docutils literal">cd bootloader</tt>.</li>
<li>Make the bootloader with: <tt class="docutils literal">python ./waf distclean all</tt>.</li>
</ul>
<p>This will produce the bootloader executables,</p>
<ul class="simple">
<li><tt class="docutils literal">./PyInstaller/bootloader/YOUR_OS/run</tt>,</li>
<li><tt class="docutils literal">./PyInstaller/bootloader/YOUR_OS/run_d</tt></li>
<li><tt class="docutils literal">./PyInstaller/bootloader/YOUR_OS/runw</tt> and</li>
<li><tt class="docutils literal">./PyInstaller/bootloader/YOUR_OS/runw_d</tt></li>
</ul>
<p><em>Note:</em> If you have multiple versions of Python, the Python you use to run
<tt class="docutils literal">waf</tt> is the one whose configuration is used.</p>
<p>If this reports an error, read the detailed notes that follow,
then ask for technical help.</p>
<div class="section" id="development-tools">
<h2><a class="toc-backref" href="#id99">Development tools</a></h2>
<p>On Debian/Ubuntu systems, you can run the following to
install everything required:</p>
<pre class="literal-block">
sudo apt-get install build-essential
</pre>
<p>On Fedora/RHEL and derivates, you can run the following:</p>
<pre class="literal-block">
su
yum groupinstall &quot;Development Tools&quot;
</pre>
<p>On Mac&nbsp;OS&nbsp;X you can get gcc by installing <a class="reference external" href="http://developer.apple.com/xcode">Xcode</a>. It is a suite of tools
for developing software for Mac&nbsp;OS&nbsp;X. It can be also installed from your
Mac&nbsp;OS&nbsp;X Install DVD. It is not necessary to install the version 4 of Xcode.</p>
<p>On Solaris and AIX the bootloader is built and tested with gcc.</p>
</div>
<div class="section" id="building-for-windows">
<h2><a class="toc-backref" href="#id100">Building for Windows</a></h2>
<p>On Windows you can use the Visual Studio C++ compiler
(Visual Studio 2008 is recommended).
A free version you can download is <a class="reference external" href="http://www.microsoft.com/express/">Visual Studio Express</a>.</p>
<p><em>Note:</em> When compiling libs to link with Python it is important
to use the same level of Visual Studio as was used to compile Python.
<em>That is not the case here</em>. The bootloader is a self-contained static
executable that imposes no restrictions on the version of Python being used.
So you can use any Visual Studio version that is convenient.</p>
<p>If Visual Studio is not convenient,
you can download and install the MinGW distribution from one of the
following locations:</p>
<ul class="simple">
<li><a class="reference external" href="http://mingw-w64.sourceforge.net/">MinGW-w64</a> required, uses gcc 4.4 and up.</li>
<li><a class="reference external" href="http://tdm-gcc.tdragon.net/">TDM-GCC</a> - MinGW (not used) and MinGW-w64 installers</li>
</ul>
<p>On Windows, when using MinGW-w64, add <tt class="docutils literal">PATH_TO_MINGW\bin</tt>
to your system <tt class="docutils literal">PATH</tt>. variable. Before building the
bootloader run for example:</p>
<pre class="literal-block">
set PATH=C:\MinGW\bin;%PATH%
</pre>
<p>Change to the <tt class="docutils literal">bootloader</tt> subdirectory. Run:</p>
<pre class="literal-block">
python ./waf distclean all
</pre>
<p>This will produce the bootloader executables <tt class="docutils literal"><span class="pre">run*.exe</span></tt>
in the <tt class="docutils literal">.\PyInstaller\bootloader\YOUR_OS</tt> directory.</p>
</div>
<div class="section" id="building-for-linux">
<h2><a class="toc-backref" href="#id101">Building for LINUX</a></h2>
<p>By default, the bootloaders on Linux are LSB binaries.</p>
<p>LSB is a set of open standards that should increase compatibility among Linux
distributions.
<cite>PyInstaller</cite> produces a bootloader as an LSB binary in order
to increase compatibility for packaged applications among distributions.</p>
<p><em>Note:</em> LSB version 4.0 is required for successfull building of bootloader.</p>
<p>On Debian- and Ubuntu-based distros, you can install LSB 4.0 tools by adding
the following repository to the sources.list file:</p>
<pre class="literal-block">
deb http://ftp.linux-foundation.org/pub/lsb/repositories/debian lsb-4.0 main
</pre>
<p>then after having update the apt repository:</p>
<pre class="literal-block">
sudo apt-get update
</pre>
<p>you can install LSB 4.0:</p>
<pre class="literal-block">
sudo apt-get install lsb lsb-build-cc
</pre>
<p>Most other distributions contain only LSB 3.0 in their software
repositories and thus LSB build tools 4.0 must be downloaded by hand.
From Linux Foundation download <a class="reference external" href="http://ftp.linuxfoundation.org/pub/lsb/bundles/released-4.0.0/sdk/">LSB sdk 4.0</a> for your architecture.</p>
<p>Unpack it by:</p>
<pre class="literal-block">
tar -xvzf lsb-sdk-4.0.3-1.ia32.tar.gz
</pre>
<p>To install it run:</p>
<pre class="literal-block">
cd lsb-sdk
./install.sh
</pre>
<p>After having installed the LSB tools, you can follow the standard building
instructions.</p>
<p><em>NOTE:</em> if for some reason you want to avoid LSB compilation, you can
do so by specifying --no-lsb on the waf command line, as follows:</p>
<pre class="literal-block">
python waf configure --no-lsb build install
</pre>
<p>This will also produce <tt class="docutils literal">support/loader/YOUR_OS/run</tt>,
<tt class="docutils literal">support/loader/YOUR_OS/run_d</tt>, <tt class="docutils literal">support/loader/YOUR_OS/runw</tt> and
<tt class="docutils literal">support/loader/YOUR_OS/runw_d</tt>, but they will not be LSB binaries.</p>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="source/Manual.rst">View document source</a>.
Generated on: 2016-01-09 16:37 UTC.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

</div>
</body>
</html>
